If you are a Web Developer and you’ve ever tried to get data from some other source on the Internet, You have come across the term REST API and a lot of documentation on how to use that API.
What is REST API?
API stands for Application Programming Interface. It is a set of rules that allow programs to communicate with each other. API is hosted on a server and the client can communicate to the server using that API.
REST stands for Representational State Transfer. This is another set of rules that the developer follows while developing an API. One such rule is that the client should get some data back when you make an HTTP Request to a specific URL.
What is an HTTP Request?
HTTP requests work as the intermediary transportation method between a client and a server. The client submits an HTTP request to the server, and the server sends back a response.
Anatomy of a Request
A request generally consists of 4 parts:
- The endpoint
- The Method
- The Headers
- The Body (or Data)
The Endpoint
The Endpoint or The Route is the base URL you make your request to. The Structure looks like
base-url/path?query
Base URL
The base-url is the starting point of any request you make to that API. For Example, the base-url of Github API is api.github.com. So all the requests you make to Github API will start with api.github.com
Path
Next comes the path, it is the resource you’re requesting data from, you can access a path the same way you access different pages on a website. To know what all paths are available for an API, you need to look through the API’s documentation.
For Example, if we look at the Github API docs , to get the repositories by a certain user the path is
/users/:username/repos
Note - Any colon (:) on a path denotes a variable and has to be replaced by an actual value.
Now to get all the repositories from my GitHub the endpoint would look like
https://api.github.com/users/sm2101/repos
Notice how I’ve replaced :username with my username sm2101
Query
The third part of an endpoint is the query, this gives you an option to modify the request with key-value pairs and each pair is separated by an ampersand (&) and the first pair always starts with a question mark (?). The structure looks like this
?query1=value1&query2=value2...
Continuing our GitHub example, there are 3 possible parameters we can use while retrieving repositories of a user
| Name | Type | Description |
| type | string | Can be all, owner, member. Default: Owner |
| sort | string | Can be created, updated, pushed, full_name. Default full_name |
| direction | string | Can be asc or desc. Default with full_name: asc, otherwise: desc |
You can use any of the above queries to alter the response to your request. If you want to get the repositories that I pushed recently, the endpoint would look like
https://api.github.com/users/sm2101/repos?sort=pushed
Next in the Anatomy of a request comes
The Method
The Method refers to the kind of request you send to the server. There are 4 types:
- GET
- POST
- PUT
- DELETE
These are used to provide meaning to the request you make and perform 4 possible actions
- CREATE
- READ
- UPDATE
- DELETE
More commonly known as CRUD
The documentation of the API you use will let you know what kind of request needs to be made for what endpoint.
Note - All the examples above were GET requests as we were ‘Getting’ data from Github.
Generally in an API, the GET endpoints are open for the public but the rest of the methods and even some GET endpoints that might return some sensitive information are protected and require authentication to access them. You wouldn’t want anyone to know your bank balance or make a transaction, would you?
The Headers
These are property-value pairs, separated by a colon(:), used to provide information like authentication or the body content to both the server and the client.
You can find a list of all the valid headers at MDN’s HTTP Header Reference
The Body
The Body or the Data is the information you want to send to the server with your request. This option can only be used with POST, PUT and DELETE requests
Note - There are different ways to send the headers and body with your request depending upon which software or utility you use.
This is almost everything you need to know about the structure of a REST API. Now if you know how to make a server you can implement your REST API and test it out using software like Postman or tools like curl for terminal etc.
If you don’t feel like creating a server, you can use something like Request Bin that allows you to create an endpoint, get a URL and then test it out.
However, if you want to learn how to create your server using Nodejs Express and MongoDB you can follow this awesome article or wait for me to write one XD
If you do try making your requests, you need to know about the
HTTP Status Codes and Error Messages
When you make a request, it either returns a successful response or something goes wrong and returns an error. HTTP status codes let you know the nature of the response quickly and you can act upon it in your application. These codes range from 100+ to 500+ and in general follow these rules
- 200+ means the request succeeded
- 300+ means the request is redirected to another URL
- 400+ means an error originated from the client-side
- 500+ means an error originated from the server-side
For example, if you make a request that requires authentication without providing one, you’ll get a status code of 401 Unauthorised, or if you request for an endpoint that doesn’t exist you get the famous 404 Not Found status code.
You can learn more about the status codes here .
Conclusion
To conclude the above article, you learned about the structure of a REST API, how an endpoint is structured, different types of requests, header and body of a request and different HTTP status codes and their general meaning.
Hope this helps you to understand any API you work with better and you can use them easily in your application.