RESTful conventions

Representational State Transfer is the name of the method used to communicate with the APIs. As the name suggests, it is stateless; in other words, the services do not keep the data transferred, so if you call a microservice sending data (for example, a username and a password), the microservice will not remember the data next time you call it. The state is kept by the client, so the client needs to send the state every time the microservice is called.

A good example of this is when a user is logged in and the user is able to call a specific method, so it is necessary to send the user credentials (username and password or token) every time.

The concept of a Rest API is not a service anymore; instead of that, it is like a resource container available to be communicated by identifiers (URIs).

In the following lines, we will define some interesting conventions about APIs. It is important to know these kinds of tips because you should do things as you would like to find them when you are working on an API. In other words, writing an API is like writing a book for yourself--it will be read by developers like you, so the perfect functionality is not the only important thing, the friendly way to talk is important too.

Creating a RESTful API will be easier for you and the consumers if you follow some conventions in order to make them happy. I have been using some recommendations on my RESTful APIs and the results were really good. They help to organize your application and its future maintenance needs. Also, your API consumers will thank you when they enjoy working with your application.

Security

Security in your RESTful API is important, but it is especially important if your API is going to be consumed by people you do not know, in other words, if it is going to be available to everybody.

• Use SSL everywhere--it is important for the security of your API. There are many public places without an SSL connection and it is possible to sniff packages and get other people's credentials.
• Use token authentication, but it is mandatory to use SSL if you want to use a token to authenticate the users. Using a token avoids sending entire credentials every time you need to identify the current user. If it is not possible, you can use OAuth2.
• Provide response headers useful to limit and avoid too many requests by the same consumer. One of the problems with big companies is the traffic or even people trying to do bad things with your API. It is good to have some kind of method to avoid these kinds of problems.

Standards

Bit by bit, more standards for PHP and microservices are appearing. As we saw in the last chapter, there are groups, such as PHP-FIG, trying to establish them. Here are some tips to make your API more standard:

• Use JSON everywhere. Avoid using XML; if there is a standard for RESTful APIs, it is JSON. It is more compact and can be easily loaded in web languages.
• Use camelCase instead of snake_case; it is easier to read.
• Use HTTP status code errors. There are standard statuses for each situation, so use them to avoid explaining every response of your API better.
• Include the versioning in the URL, do not put it on the header. The version needs to be in the URL to ensure browser explorability of the resources across versions.
• Provide a way to override the HTTP method. Some browsers only allow POST and GET requests, so it will be good to allow a X-HTTP-Method-Override header to override PUT, PATCH, and DELETE.

Consumer amenities

The consumers of your API are the most important, so you need to provide useful, helpful, and friendly ways to make the developer's job easier. Develop the methods thinking about them:

• Limit the response data. The developer will not need all the available data, so you can limit the response using a filter for the fields to return.
• Use query parameters to filter and sort results. It will help you simplify your API.
• Remember that your API is going to be used by different developers, so look after your documentation--it needs to be really clear and friendly.
• Return something useful on the POST, PATCH, and PUT requests. Avoid making the developer call to the API too many times to get the required data.
• It is good to provide a way to autoload related resource representations in the response. It would be helpful for the developers in order to avoid requesting the same thing many times to get all the necessary data. It is possible to do this by including filters to define specific parameters in the URL.
• Make the pagination using link headers, then the developers will not need to make the links on their own.
• Include response headers that facilitate caching. HTTP has included a framework to do this just by adding some headers.

There are a lot more tips, but these ones are enough for the first approach to RESTful conventions. In the subsequent chapters, we will see examples of these RESTful conventions and explain how they should be used better.