Restful API Design

Everyone keeps building APIs and you must have heard the term Restful API development. I just want to give a short overview of that. You can and probably should read the rules in more detail, if you plan to make a career in app and api development.

Rest My Case

Designing a REST API raises questions and issues for which there is no universal answer. REST best practices are still being debated and consolidated, which is what makes this job fascinating.

There are 5 basic and important rules in Restful development

Resources

Your resource is the URI (Uniform Resource Identifier), when naming it use nouns not verbs. For eg. don’t name it like getBooks(), createUsers() etc. Name it like
GET /api/books
POST /api/users

This is how your logic is identified, you should always choose a suitable name. There are 3 name cases you can use to name your resources, Choose one and stick to it.

  • camelCase
  • spinal-case
  • snake_case

HTTP Methods

This is to identify the action your api is going to perform. The HTTP protocol is used for communication hence the methods used are also HTTP methods. These are to perform your CRUD operation on a resource

The methods that are mostly used are :

  • GET : This is to retrieve information from the server and database using a URI. Requests using GET should only retrieve data and should have no other effect on the data.
  • POST : This is to send and add a data object to the server.
  • PUT : This is to update current data in the server
  • DELETE : This is to delete a data from the server

HTTP Headers

This is to provide information about the request and response to the resource URI. This helps in creating the request or response format.

These are of 4 types:

  • General Header : applicable to both request and response and does not apply to the content itself. Example Date, Cache-control, Connection etc.
  • Client Request Header : This has more information about the resource to be fetched or request. Example Accept, User-Agent, Cookie etc.
  • Client Response Header : This has additional information about the response. Example Content-Type, Content-Encoding etc.
  • Entity Header : This has the information about the entity meta data. Example Host, Content-Length, User-Agent etc.

Status Codes

It is paramount that the Restful API you make should return the correct status codes for the client to understand the status of the action.

There is a huge list of status code which you can find here, I am going to mention the most common ones here

  • 200 : OK — everything was successful
  • 201 : Created — a new data was successfully created
  • 304 : No change — the request is being responded back from the cache
  • 400 : bad request — request was invalid
  • 401 : unauthorised — unauthorised to perform the action you are trying to
  • 404 : resource not found — no resource of that name exists
  • 500 : Internal Server Error — something went wrong on the server side

In general,

  • 2XX : The action was successful
  • 3XX : additional action is required to complete the request
  • 4XX : Client side errors
  • 5XX : Server side errors

Query Parameters

The query parameters (params) are given for following purposes

  • pagination
  • filtering
  • sorting
  • searching

Conclusion

Restful API design are just guidelines to easy and quick API development. It is the most popular because

  • lightweight in nature
  • Easy and fast to develop
  • Industry Standard

This along with earlier posts should get you started with API development comfortably.

Next post due by Sunday.