Like most computer software, APIs must mirror the human requirements. API is slightly different from a graphical user interface because APIs communicate with a computer programmer instead of directly interacting with the top user. However, the principles that are valid for the end user’s requirements need to be respected – you have to think about the background knowledge the developers are bringing in and take into consideration the constraints of their work. A bandwidth of mobile devices is one of the possible constraints, for example.
Today, many developers release low-quality APIs that barely fulfill the CRUD functions. CRUD is an abbreviate for Create, Read, Update, Delete functions. On the other side, some other developers invest a lot of effort and produce APIs that go even beyond the CRUD function. They are trying to incorporate functions the users requested, for example, Buy or Reserve. This has a result of producing a structure that will reach maximum efficiency.
The basics of RESTful API design
API clients see the resources through representations. RESTful APIs don’t transfer the resources to the users directly but via representations of those resources. To show resources in the representative form, you should use JSON or XML media types. This way, clients don’t have direct access to resources. Because of this, clients need actions that will replace the state of the resources. Here happens the transfer, which serves for “T” in REST term.
Note that REST stands for an architectural style. It actually defines the system functions. When people talk about REST APIs, they usually associate it with HTTP, but the truth is that REST is not limited to HTTP only.
Interesting, one of the HTTP authors created REST too. Probably that is the reason why these two fit in very well, as they have similar basic elements, such as:
- Media types – JSON, XML, and HTML,
- Uniform resource locators,
- Built-in methods, which implement REST actions. Each of the methods has some special characteristic, which should be considered when it comes to actions’ implementation.
REST takes advantage of existing protocols, mostly of HTTP. Developers have less job this way, as they don’t have to install additional software to benefit from REST API design. Dr. Roy Fielding explained how to design REST API, putting an accent on flexibility here.
In order to build a well-designed API, you should create it so it fulfills the needs of different categories of customers. REST is not limited to XML, such as SOAP. It actually can associate with JSON, YAML, XML, or some other format according to the client’s needs.
One of the REST API design faults lies in the possibility of losing state defined as REST. Some of these constraints cover client-server concept (client-server decoupling goes through a uniform interface), stateless REST condition, increased storage of cached data, code on demand, and layered system.
A final word
REST API design produces complex, powerful, and flexible APIs. In order to design a good API, you have to go through the REST basics a couple of time and understand its constraints fully.
