What makes REST API really usable?

REST APIs are the most critical part of every application today, be it a blog or an application which is running on your mobile phone. But what makes REST API really usable?

Before we go ahead, I don't think REST or API requires any introduction today! And if you are unaware of it, then you need to catch a learning train that takes you there immediately.

I have been working on enterprise applications for a decade now and I have seen APIs from the worst to the best. Following are some of the points which I think are the most important aspects while designing the REST APIs, which makes them really useful.

Client Agnostic

This is one of the most important point while designing the REST APIs. You should never design the APIs by focusing only on a specific client e.g. Web UI of your application. Today, it is very critical to have presence on the mobile handsets along with having a Web application.

You want to engage with all type of users so having all possible set of interfaces is very crucial. If you design your APIs to be very specific with a single client in focus, they may not work on other platform or can cause problems while developing applications on other platform.

E.g. Just because your Web UI uses error code 404 to report some errors, you should not change the status code to 406 or 409.

Organized

If you do not organize your APIs properly then it's going to be cumbersome for the clients to use them efficiently in their applications. E.g. an organization allows users to register and place orders on the website and you are designing APIs for the administration section. Following URL is a very bad way of exposing an endpoint,

GET /list/users

Instead it URL should be,

GET /users

and then the to get information about user and the orders by user should use,

GET /users/1         // Fetches the user information with id 1
GET /users/1/orders  // Fetches the list of orders placed by user with id 1

Primary entities in the application should define the root of endpoint and subsequent paths should be used to expose information about these entities.

HTTP Methods and status codes

It's very important to understand the role of HTTP methods and the status codes. If your API is returning status code 200 for every type of response then it's a blunder and you need to fix it now!

Every HTTP method is has it's meaning and it should be honored,

GET    - Fetch resource from server, not accepting anything in body!
POST   - Create a new resource on server
PUT    - Create or update an existing resource
DELETE - Delete specified resource on the server

Along with methods, every status code has meaning and API clients always expect accordance to it.

200  - Request was successful and may have data in body
201  - Creation of resource was successful
204  - Request was successful and there is nothing to return in body
301  - Resource has been moved and client should use given location for all new requests
307  - Resource is temporarily moved to new location

For more information, check HTTP status codes.

Filter and pagination

APIs should always support filtering of data so that clients can fetch only required information instead of receiving entire data which may not be useful for it. Another reason for this is API Clients also want to make sure that the application is fast and responsive, so they do not want to waste time in accepting the bulk of unused data.

Same as filtering, pagination is also one of important factor. Instead of fetching everything and paginating on the client side, it's always better to support pagination from server side so that the client application can run fast and smooth.

Another major mistake people do while designing APIs is having different set of parameters for pagination for different APIs. Parameter names should be consistent in all the APIs to make the life of API clients easy.

These are not all, there are many things which are important while designing APIs and making them really useful but I have seen developers, organizations making mistakes in these areas especially.