Abcd
I attended the MLH Nyeri at the DeKUT Innovation Hub (DeHUB) to give a talk on how to make good APIs. The event was amazing — we had good food, fun ninjas, interesting ideas and a tone of amazing games to play. I thank the organizers of the event — Microsoft, GitHub, DSC Kimathi and CSOK. I will share what I said at the event here. Some of my ideas are from Mahesh’s blog.
Rule 1: Common Terminologies
The following are the most important terms related to REST APIs
- Resource — is an object with a type, associated data, relationships to other resources, and a set of methods that operate on it. eg Articles and CRUD operations can be performed on it
- Collection — Resources can be grouped into collections. Each collection is homogeneous so that it contains only one type of resource, and unordered.
Rule 2: API Endpoints
A good api endpoint should contain nouns (we can also call them resources )only and no verb should be used. Lets take an example of bad endpoints and rewrite them
- getAllArticles
- createNewArticle
- updateArticle
We can improve these endpoints by using a noun only, and in plural form.
method GET with endpoint /articles to return a listing of all articles.
method POST with endpoint /articles to create a new articles.
method PUT with endpoint /articles/1 to update a specified articles
Thus we will have a collection with HTTP verbs and endpoints as:
- GET /articles
- POST /articles
- PUT /articles/1
Rule 3: HTTP methods
There are a couple of methods which can also be referred to as verbs by HTTP. Here I will look at the most common ones.
- GET — Use GET requests to retrieve resource representation/information only — and not to modify it in any way. As GET requests do not change the state of the resource, these are said to be safe methods. Additionally, GET APIs should be idempotent, which means that making multiple identical requests must produce the same result every time until another API (POST or PUT) has changed the state of the resource on the server.
- POST — Use POST APIs to create new subordinate resources, e.g. a file is subordinate to a directory containing it or a row is subordinate to a database table. Talking strictly in terms of REST, POST methods are used to create a new resource into the collection of resources.
- PUT — Use PUT APIs primarily to update existing resource (if the resource does not exist then API may decide to create a new resource or not).
- DELETE — As the name applies, DELETE APIs are used to delete resources (identified by the Request-URI).
Rule 4: HTTP response status codes
We can categorize response code in 5 categories.
1xx: Informational — Communicates transfer protocol-level information.
2xx: Success — Indicates that the client’s request was accepted successfully.
3xx: Redirection — Indicates that the client must take some additional action in order to complete their request.
4xx: Client Error — This category of error status codes points the finger at clients.
5xx: Server Error — The server takes responsibility for these error status codes.
Now look at subset of codes that specially apply to the design of a REST APIs — in some more detail.
200 (OK)
It indicates that the REST API successfully carried out whatever action the client requested, and that no more specific code in the 2xx series is appropriate.
Unlike the 204 status code, a 200 response should include a response body.The information returned with the response is dependent on the method used in the request, for example:
- GET an entity corresponding to the requested resource is sent in the response;
- POST an entity describing or containing the result of the action;
201 (Created)
A REST API responds with the 201 status code whenever a resource is created inside a collection. There may also be times when a new resource is created as a result of some controller action, in which case 201 would also be an appropriate response.
The newly created resource can be referenced by the URI(s) returned in the entity of the response, with the most specific URI for the resource given by a Location header field.
