General Questions

Table of Contents

• At a high level, how does the CommandSocket framework actually work?
• What is a CommandSocket API, and why is it better than something like an HTTP-based API?
• What is namespacing in the context of CommandSockets, and why is it important?
• What is the difference between Command Sets and Command Registries?

---

Q: At a high level, how does the CommandSocket framework actually work?

TODO

Q: What is a CommandSocket API, and why is it better than something like an HTTP-based API?

To answer this question, it might be best to compare it to a traditional HTTP-based API, so let's make that analogy.

In an HTTP-based API, some client (such as your web browser) makes a request to a HTTP server. This request might come in a number of different forms, such as a POST, GET, or maybe a PUT request. The request would be identified to a certain path on the server, let's take http://api.mywebsite.com/users for example. Putting this all together, the very basics of this request would look something like the following:

PUT http://api.mywebsite.com/users
{
    'username': 'johnnysmith',
    'email': '[email protected]'
}

Lets say that what this request is doing is modifying the user 'johnnysmith' by changing his email address to '[email protected]'.

That second part of the above request (the request body) would be processed by the server, and (hopefully) soon after, the server would (hopefully) respond with a 200 status code, meaning that the request went through A-OK, and all is good. This is great! We can do the exact same thing with the CommandSocket framework:

// misc. setup and initialize of the connection

let updatedUserInfo: UserInfo = await myCommandSocket.invoke("my-website users modify", {
    username: "johnnysmith",
    email: "[email protected]"
});

So far, we can't really see any benefits of using CommandSockets over just a simple HTTP-based API, right?

Well, let's add to our API example a little bit.

Let's say that we want to immediately update this information for everyone who is currently on our site. We don't have time to refresh the page every time something changes, and besides, how would we know when we even need to refresh? Should we just refresh constantly?

Using a traditional HTTP-based API, we have now run into a problem. In order to immediately update clients when information is changed, we need some way to inform them as soon as the information changes. We do not want to wait to inform clients until the next time they make a request, as this means that is it possible that clients who have accessed the information recently but are not making additional requests to the server will be working with out-of-date/incorrect information and have no indication of this.

            HTTP API

CLIENT                     SERVER
  |                           |
  |----------REQUEST--------->|      Client to server communication.
  |<---------RESPONSE---------|
  |                           |
  |<----X----REQUEST-----X----|      Server to client communication.
  |-----X----RESPONSE----X--->|      NOT POSSIBLE WITH HTTP!
  |                           |

Within the HTTP standard there is simply no way for a server to initiate an interaction with a client. Because of this we can come to the conclusion that HTTP just does not provide the tools we need to accomplish the task at hand.

And thus, this is where the CommandSocket framework truly shines. The CommandSocket framework provides a duplex/bi-directional communications framework to address just such issues.

         CommandSocket API

CLIENT A                    CLIENT B
   |                           |
   |----------REQUEST--------->|      Client A to client B communication.
   |<---------RESPONSE---------|
   |                           |
   |<---------REQUEST----------|      Client B to client A communication.
   |----------RESPONSE-------->|      Possible with the CommandSocket framework!
   |                           |

So to answer the original question, a CommandSocket API is a means by which developers can create APIs that not only complete the traditional task of answering questions, but can also ask them back!

Q: What is namespacing in the context of CommandSockets, and why is it important?

'Namespacing', in the context of CommandSockets, refers to the practice of forming command identifiers in such as way as to avoid naming collisions between similar commands from different command sets.

TODO

Q: What is the difference between Command Sets and Command Registries?

TODO