Endpoints, HTTP verbs, and HTTP status codes

The main way developers interface with a given API is through an endpoint, which is simply a URL that developers can perform HTTP requests against. But what HTTP requests can be performed? And what information must the developers send to the server and what information do they get back? These are all important considerations that must be taken into account when developing a REST API.

Designing REST APIs

Some of these elements are fairly obvious: the base domain is how users know they are interacting with your organization, but the product part usually requires a bit more thought. As companies grow, so does their product portfolio and, usually, their API portfolio. Organizing these APIs into URLs that users can correlate correctly to their products is no easy and requires a lot of thought. It also has the advantage of allowing different APIs to be managed independently by different teams. The version element exists because APIs evolve over time and API versioning is a great way of not breaking the software your users have built on top of your API. Finally, resource is the name of the resource users are trying to access/create/modify/delete and it is usually identified by its ID.

HTTP status codes and verbs

When performing an HTTP request, you have to specify the HTTP verb you want to use, which depends on the action you want to carry out on your resource, and the same is true for the client in the client-server architecture model. Keep in mind that whoever designs the API also decides which HTTP verbs perform which actions, so it is always best to read documentation (and pray that it exists). A request can also provide additional information in the form of HTTP headers, for example, content-type is usually used to indicate the original media type of the resource. Query parameters are usually used to get subsets of the data or indicate which page of the returned content we want to look at while the HTTP body is commonly used to specify the content we want to create of the fields of the content we want to modify. Likewise, the HTTP response can also contain HTTP headers and body.

The request and response must be specified independently for each of the HTTP methods, all of which should be outlined in the Uniform Interface that should define:

• An endpoint;
• Allowed query parameters;
• HTTP verbs;
• HTTP headers for both the response and request and should especially be defined in the case of custom headers;
• Request/response body format and schema.

Additionally, when we perform a request, the HTTP response always has another field that indicates how our request went: the HTTP status code. The values that this code might take fall into one of five categories:

• 1xx - informational;
• 2xx - success;
• 3xx - redirection;
• 4xx - client error;
• 5xx - server error.

Again, these status codes are a convention, and a pretty unanimous one at that, but it still does not guarantee that the API designer has included HTTP status codes in the responses according to this convention. Always read the documentation (and when you are writing your own API, do not invent new HTTP codes, please).

Regarding HTTP verbs, there are also some conventions on what action each verb should translate to:

• POST should translate to creating a resource;
• GET should translate to fetching a resource;
• DELETE should, well, translate to deleting a resource.

For updating a resource, this is where it gets murky. There are usually two verb options for this action: PUT and PATCH. General convention dictates that PUT should be used to update all attributes of the resource, or create it if it doesn’t exists, while PATCH is used to update a subset of the resource’s attributes. Fundamentally, it is up to the API designer to decide which HTTP verb they want to use for update operations.