<commit_before>---
layout: post
title: "REST API Best Practices"
excerpt: "Some points to take into consideration when designing an API"
tags: [api, rest, practices, http, ssl]
date: 2019-01-27T21:22:08+02:00
comments: true
image:
  feature: posts/cover-api.jpg
---

I've been working a lot with APIs during the last few years, either developing them or integrating with third party APIs.
So I've decided to gather some of the knowledge I gained along the way and write about it here.
Many of the APIs I've integrated with didn't follow any kind of pattern, so their documentation had to be consulted more often than if they were following some of the points below.
Because of that, some of them couldn't even be considered RESTful APIs.

## What is REST?

REST means Representational State Transfer, and it is a software architectural style that defines a set of rules to be used when creating APIs. The APIs that conform to the REST style are called RESTful APIs.
First, you need to create one or more endpoints and expose them to your clients. Then, your clients are able to access them via HTTP using the correct HTTP methods.

## HTTP methods

The GET method happens when you open a website and it retrieves an image from the server, for example.
The POST method is often used on forms in websites, so your data is not sent in the URL (query string), but in the body of the request in this case. A RESTful API will use these two HTTP methods in their specific cases, but also some others like PUT and DELETE.

Let's see some points to take into consideration when designing an API.

## Endpoints should be nouns, not verbs

Think of a resource you have in the system. For example, you have a collection of employees. If your client wants to retrieve a list of employees, he doesn't need to remember he has to access the URL /getEmployees. Or even worse, what if this method was called /getAllEmployees, or something else?
Then your client would have to remember if the method for deleting an employee was /removeEmployee or /deleteEmployee, for example, and use the HTTP Method POST for that?

What if you could follow a pattern that would make much more sense for everybody? The HTTP protocol already comes with methods you can implement on your API for your client to interact with, so that makes it more intuitive.

Let's suppose you have a collection of employees in your database, and you want to return all of these employees.

Then your client will make an HTTP GET request to the /employees endpoint for that.

The most used form when naming an endpoint is the plural, so employees instead of employee in this example, as we're returning a list with all the employees.

It makes much more sense this way, but if you insist in using the singular form (I wouldn't recommend), it's important that you keep the same pattern also in the other endpoints you create.

## Use the correct HTTP methods

Following our GET /employees example, which returns a list of employees, what happens if we need to create, update, delete an employee, or retrieve just a single employee? There are HTTP methods for each of these cases:

### POST

The HTTP POST method is the one for when you want to create a resource, so the client will POST to /employees, sending the data in the request body instead of in the query string. If the request body contains any array, the best practice is to stringify that array. I've seen people sending something like this for the server to parse:

{% highlight json linenos %}
{
  "termsOptions[0].key": "optionSMS",
  "termsOptions[0].value": "true",
  "termsOptions[1].key": "optionPhone",
  "termsOptions[1].value": "true"
}
{% endhighlight %}

Instead of just simply sending a stringified array.

### PUT

The HTTP PUT method is the one you use when you want to update a resource. Before accessing this endpoint, the client will need to retrieve the employees, so it is able to know the id of the employee it wants to update.

An endpoint with a PUT request is accessed by sending HTTP PUT to /employees/:id, being :id the id of the chosen employee. In the body of the request must be the object that represents the employee, with the changes the client needs to make.

Ps: I've seen some (very few) APIs implementing the HTTP PATCH method to allow the partial update of a resource, but from experience, that's not much used. So I'd rather keep it simple and use only PUT for updating.

### DELETE
<commit_msg>Added some text to Use the correct HTTP methods<commit_after>---
layout: post
title: "REST API Best Practices"
excerpt: "Some points to take into consideration when designing an API"
tags: [api, rest, practices, http, ssl]
date: 2019-01-27T21:22:08+02:00
comments: true
image:
  feature: posts/cover-api.jpg
---

I've been working a lot with APIs during the last few years, either developing them or integrating with third party APIs.
So I've decided to gather some of the knowledge I gained along the way and write about it here.
Many of the APIs I've integrated with didn't follow any kind of pattern, so their documentation had to be consulted more often than if they were following some of the points below.
Because of that, some of them couldn't even be considered RESTful APIs.

## What is REST?

REST means Representational State Transfer, and it is a software architectural style that defines a set of rules to be used when creating APIs. The APIs that conform to the REST style are called RESTful APIs.
First, you need to create one or more endpoints and expose them to your clients. Then, your clients are able to access them via HTTP using the correct HTTP methods.

## HTTP methods

The GET method happens when you open a website and it retrieves an image from the server, for example.
The POST method is often used on forms in websites, so your data is not sent in the URL (query string), but in the body of the request in this case. A RESTful API will use these two HTTP methods in their specific cases, but also some others like PUT and DELETE.

Let's see some points to take into consideration when designing an API.

## Endpoints should be nouns, not verbs

Think of a resource you have in the system. For example, you have a collection of employees. If your client wants to retrieve a list of employees, he doesn't need to remember he has to access the URL /getEmployees. Or even worse, what if this method was called /getAllEmployees, or something else?
Then your client would have to remember if the method for deleting an employee was /removeEmployee or /deleteEmployee, for example, and use the HTTP Method POST for that?

What if you could follow a pattern that would make much more sense for everybody? The HTTP protocol already comes with methods you can implement on your API for your client to interact with, so that makes it more intuitive.

Let's suppose you have a collection of employees in your database, and you want to return all of these employees.

Then your client will make an HTTP GET request to the /employees endpoint for that.

The most used form when naming an endpoint is the plural, so employees instead of employee in this example, as we're returning a list with all the employees.

It makes much more sense this way, but if you insist in using the singular form (I wouldn't recommend), it's important that you keep the same pattern also in the other endpoints you create.

## Use the correct HTTP methods

Following our GET /employees example, which returns a list of employees, what happens if we need to create, update, delete an employee, or retrieve just a single employee? There are HTTP methods for each of these cases:

### POST

The HTTP POST method is the one for when you want to create a resource, so the client will POST to /employees, sending the data in the request body instead of in the query string. If the request body contains any array, the best practice is to stringify that array. I've seen people sending something like this for the server to parse:

{% highlight json linenos %}
{
  "termsOptions[0].key": "optionSMS",
  "termsOptions[0].value": "true",
  "termsOptions[1].key": "optionPhone",
  "termsOptions[1].value": "true"
}
{% endhighlight %}

Instead of just simply sending a stringified array. Please, keep it simple and send a stringified array instead, in cases like this one.

### PUT

The HTTP PUT method is the one you use when you want to update a resource. Before accessing this endpoint, the client will need to retrieve the employees, so it is able to know the id of the employee it wants to update.

An endpoint with a PUT request is accessed by sending HTTP PUT to /employees/:id, being :id the id of the chosen employee. In the body of the request must be the object that represents the employee, with the changes the client needs to make.

Ps: I've seen some (very few) APIs implementing the HTTP PATCH method to allow the partial update of a resource, but from experience, that's not much used. So I'd rather keep it simple and use only PUT for updating.

### DELETE

{'fraction_non_alphanumeric': 0.04566159315631597, 'fraction_numerical': 0.004888345739362293, 'mean_word_length': 4.236765561372891, 'pattern_counts': {'":': 8, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2483948', 'n_tokens_mistral': 2304, 'n_tokens_neox': 2147, 'n_words': 1515}