Designing as RESTful API is something we got used to as web developers in a way that sometimes we do it blindfolded. But there is more for REST APIs to be just a simple 200 JSON body response.

You see, when we learned REST we definitively found that we can use HTTP methods (VERBS) in order to express different operations but there are some details that will make your API more understandable, modern and enterprise-grade.

Back to basics: HTTP

In order to better design REST API, you’d better know the HTTP protocol basics, you can check this link to learn more. Here is a list of things you must know before designing a REST API:

  • HTTP has verbs (or methods): GET, POST, PUT, PATCH and DELETE are the most common.
  • REST is resource-oriented and a resource is represented by an URI: /articles/.
  • An endpoint is the combination of a verb and an URI, e.g. GET: /articles/.
  • An endpoint can be interpreted as an action on a resource. For example, POST: /articles/ may mean "Create a new article".
  • At a high-level, verbs map to CRUD operations: GET means Read, POST means Create, PUT and PATCH mean Update, and DELETE means... well, Delete.
  • A response’s status is specified by its status code: 1xx for information, 2xx for success, 3xx for redirection, 4xx for client errors and 5xx for server errors.

Of course you can use anything the HTTP protocol offers for REST API design, but these are basic things I believe you need to keep in mind.

Avoid plain text

It is clearly not imposed by REST architectural style, but most of them use JSON as a data format.

If you think it’s enough to return the plain data, you’re wrong, you must specify the Content-Type header too! It must be set to the value application/json.

URIs crafting

Never use verbs in URIs, As you know HTTP methods are verbs, so using verbs in your URI will make it look awkward. Make sure you follow the REST principle which is resource oriented.

Use HTTP protocol verbs to describe actions on the desired resource defined in the URI.

Plural nouns

When designing a RESTful API avoid using singular nouns to describe a resource. Always think of a resource in a URI as a repository which contains one or many resources of the same type. So make sure you use plural nouns (e.g: /articles/{id} instead of /article/{id}).

Wrap your response

Wrap your returned response in a standard model that will enable the client to know what went wrong in case of a problem and to make sure that your baseline model structure never changes when the data changes.

For example when using pagination, use a model that defines the offset and page size. Always make sure that your data is accessible via the same field, for example:

For GET:/articles?offset=40&limit=10 we get:

{
  "error": null,
  "didError": false,
  "model": [{
    "title": "I am a test data",
     ...,
  }],
  "offset": 40,
  "limit": 10,
}

For GET: /articles/156

{
  "error": null,
  "didError": false,
  "model": {
    "title": "I am a test data",
  }
}

For PUT: /articles/156

{
  "error": null,
  "didError": false,
  "model": {
    "title": "I am a test data",
  }
}

You can see that the first model will be used in all paginated list responses while the other one will be used in all single entry responses.

Status codes are your friend

This is very important as all HTTP client rely on this, make sure you use the standard HTTP status codes ranges correctly. This means that you can use authorized ranges and most importantly to use them depending on the usecase.

In REST API design, it is recommended that you use these codes for different operations:

GET: 200 OK
POST: 201 Created
PUT: 200 OK
PATCH: 200 OK
DELETE: 204 No Content
  • 👉 403 Forbidden.

Use 202 for future processing

I find 202 Accepted to be a very handy alternative to 201 Created. It basically means:

I, the server, have understood your request. I have not created the resource (yet), but that is fine.

There are two cases which I find 202 Accepted to be especially suitable for:

  • If the resource will be created as a result of future processing — e.g. after a job has finished.
  • If the resource already existed in some way, but this should not be interpreted as an error.

Conclusion

In this article we just treated the basics in REST API design, you can find better resources in google that addresses this subject in depth with more examples and even sample projects.

Have fun designing an API that adopts good semantics, common sense and simplicity.

This blog was first published in Medium

Read also on Gomytech: