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 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.
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:
POST
and GET
requests, so it will be good to allow a X-HTTP-Method-Override
header to override PUT
, PATCH
, and DELETE
.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:
POST
, PATCH
, and PUT
requests. Avoid making the developer call to the API too many times to get the required data.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.