Hello there, my friend,
Today we resume with the 2nd part of our 4-part series on APIs. In case you missed the 1st part this is the article on 1st part of the series. I assume that you have read the 1st part of the series already. With that taken care of, let us go over the steps in an API call. In this post, we will view a few key terms and notable differences.
An overview of the steps
1. Client constructs requests as a URI.
2. Send the request from the Client to the Server
3. The Server will retrieve and parse the resource
4. The Server will generate the response
5. The Server will send this response back to the Client in a suitable representation
There are a few notable words mentioned above. I see the following.
- Client
- Server
- URI
- Resource
- Request
- Parse
- Representation
Clients vs Servers
For API calls to exist, there must be a sender and a receiver. The sender is the Client. He is asking the question of the receiver. The receiver then responds with the answer.
Think of it like your everyday conversation. Someone asks a question, and the other fellow responds. That is the same situation we have here.
Requests vs Parsing
Each API call sends information over to the receiver (i.e. the Server ). The server needs to make sends of the incoming message or call. The process of making sense of this information is parsing. But how can the server know how the request is coming to parse it correctly.
Just like your normal conversation, we have a pre-defined agreement that we will speak in a specific language ( e.g. English ). If you should suddenly start speaking another language, then the conversation cannot continue. It is the same way with API calls. A predefined agreement would have been reached that establishes this.
URIs vs Resources
You likely may have heard of URIs and Resources. What is the difference between these? Well, let us consider the following
From the above http://agenu.com/user/123 and http://agenu.com/user are URIs. Whilst, user and user/123 are the resources.
Speaking resources are found within the URI.
Representation vs Resources
Think of it this way; if the resource is the question, then a representation is the answer based specifically on the question which is being asked. Each representation has a set of attributes based on a resource. Let’s put an example on it. Perhaps that will help.
http://agenu.com/user/123 will return a representation of the resource user/123
This could produce an output of
{ "name": "Eli", "city": "Accra" }What we are doing is asking who the user with ID 123 is. The output returned gives us all the details we need to know about the user with ID 123. It is as simple as that.
Rules for naming resources
Everybody in the world could come up with their way of naming resources. However, you would usually see the conventions below. These are also usually best practice:
Use the forward slash to show child objects, such as
*/users – show all users
*/ users /rights – show all rights
*/ users / rights /1 – show rights with id 1
Lastly, the name and structure of URIs should convey meaning to your clients.
Conclusion
I know we have handled a significant part of APIs here. However, I will want you to re-read it. Ask me questions that you would want clarity on. I will be happy to respond. In the next post, we will get into the very specific methods used for making these API calls.
Until we meet again later, keep learning.
Cheers!
