If you have plans to build an API, then make sure that it will be useful for the clients and consumers. In order to design a good API, there are some requirements that you should follow. For example, ensure the independence of the platform and produce an API that will be able to evolve. Client applications will function without any modifications as the API evolves. Make all the API functions discoverable, so clients can use it freely.
Table of Contents
Representational State Transfer and resources
Dr. Roy Fielding presented new, architectural way for web services designing. Concluding – REST is an architectural style. It builds systems based on hypermedia. REST doesn’t have to be connected with HTTP, as it is pretty independent. Yet, HTTP as an application protocol is commonly used within REST implementations. The most significant advantage of REST is the use of open standards.
If you want to design a RESTful API using HTTP, design it around resources. By the term resources we mean any kind of service, object or data that are open for client access.
When we talk about REST design, resources usually refer to data or objects, while REST endpoint design refers to the URL.
Another thing to remember about RESTful API design using HTTP is that each resource has an identifier. This identifier explains and identifies resources, and that is URI.
Representations explain and express resources. Further, clients communicate with services through these representations. JSON is the most common exchange format.
Principles that will help you build an awesome RESTful API
Simplicity,
Make the base URL as simple as possible.
Use nouns,
Some developers use verbs instead of nouns – this is a mistake. HTTP methods actually describe APIs with verbs, so there is no need for developers to do so.
Discover which is the best HTTP method for your API,
Numerous HTTP methods assign the type of operation for the API performing. Some of the most common methods are post, get, delete, and patch. Get refers to collecting resources, post creates resources, patch updates them, while delete erases them.
Post, delete, and patch may alter the state. Don’t use the get method for state changes. It is very important to define which HTTP method is the right choice for a given operation.
Use plural names,
Developers often get into a debate when it comes to singular or plural names of resource URL. However, if we use a singular name we don’t specify if we are talking about one resource or about a resources collection. If we use plural names, it makes things much more clear and defined. Only plural nouns refer to plural resources.
HATEOAS,
Developers should use hypertext links to create or improve navigation through the API. This principle is better known under the HATEOAS abbreviate, which means hypermedia as the engine of application state.
Conclusion
APIs enable you better communication, which is more than evident. However, badly designed API, it will bring in confusion. Make sure you stick to the principles we exposed above and you will get an awesome API.