RESTFUL API Design – Application Guide

We, as software developers, use or build REST API on a daily basis. APIs have now become the default relationship between systems. Amazon is the best example of how much APIs can be used effectively for communication. In this article, we are going to talk about how to design the Restful API optimally to prevent mistakes.

Jeff Bezos’s command

You’ve probably heard Jeff Bezos’s command to Amazon developers so far. If you haven’t heard it is as follows:

  1. All the teams are now providing their data and functions through service interfaces.
  2. Teams have to communicate through these interfaces.
    No other type of intra -installment is allowed, direct linking, direct reading of each other’s data, a memory sharing model, or any back door. The only permissible communication method is to call service interfaces on the network.
  3. No matter what technology you use, HTTP, Corba, PUBSUB or any custom protocol you use doesn’t matter to Bezos.
  4. All service interfaces should be redesigned from the beginning to be external. This means that the team must
  5. have a plan that can provide the interface to the developers of the outside world. There are no exceptions.
  6. Anyone who does not do so will be fired.

Eventually it was revealed that this was the key to Amazon’s success. Amazon was able to build scalable systems and then managed to offer these systems as services such as Amazon Web Services.

RESTFUL API Design - Application Guide

Design concepts Restful API

In this section, we will learn about the concepts you should follow when designing the Restful API.

Simple design

We need to make sure that the URL is the basis of the API simple, for example, if it wants to design APIs for products, it should be something like:

/products

/products/12345

The first API receives all the products and the second API receives a special product.

Use the noun (and not the verb)

There are many developers who make this mistake. They generally forget that we have HTTP methods that better describe the APIs and so use the verb in the URLs of the APIs. For example API receives products as follows:

/products

And should not be as follows:

/getAllProducts

These are some common URL patterns we’ve seen so far.

Use appropriate HTTP methods

Restful APIs have different methods that display the type of operation we want to run API.

  • Get – to get a resource or set of resources.
  • Post – To create a source or set of resources.
  • PUT/PATCH – To update the source or set of existing resources.
  • Delete – to delete existing resources or set of resources.
  • We need to make sure we use the appropriate HTTP method for any operation.

Use the plural mode

This is a little controversial. Some people like the source URL to have the names and others like to be singular. For example:

/products
/product

We recommend using the plural mode, as it ends confusion about whether we want to get a singular or collective source of resources. Also, avoid adding additional items such as attaching ALL to the base URL as follows:

/product/all

Some people may not like this, but we suggest keep this situation uniform throughout the project.

Use the parameters

Sometimes we need to have an API that shows us something more than ID. In these cases, we can use the query parameters to design API.

  • ‘Products? Name =’ abc/ preference to GetProductsbyname/ preference.
  • ‘Products? Type =’ xyz/ prefers to GetProductsbyType/.

This will avoid the emergence of long URLs and keep the design simple.

Use the right http codes

There are a lot of HTTP code, but most developers eventually use two 200 and 500 codes. This is definitely not a good procedure. Here are some HTTP code.

  • 200 OK – This is the most common code used by HTTP, indicating that the operation has been successful.
  • 201 Created – This code can be used when the Post method must create a new source.
  • 202 AcceptED – This code is used to announce this issue that is requested to the server.
  • 400 Bad Request – This code is used when the client’s input validation is unsuccessful.
  • 401 Unauthorized / 403 Forbidden – This code is used if the user or system is not allowed to perform specific operations.
  • 404 Not Found – This code was used when we were looking for a specific source and not available on the system.
  • 500 Internal Server Error – This code is never explicitly issued, but may be issued in case of system error.
  • 502 Bad Gateway – This code is used when the server has received an invalid response from its upstream server.

Copying

API-copying is very important. Many different companies use versions in different ways. Some use duplicates in date, and others use queries parameter. Normally, it is best to keep the version as a prefix for the source. Note the following example:

/v1/products

/v2/products

We should also avoid using the following method:

/v1.2/products

The above method means that the API can be changed repeatedly. The dot may also not be easily seen in URL-. So keep it simple. The appropriate procedure is also to always have a back -up. This way, if the API version is changed, consumers will have the opportunity to upgrade to the next version.

Use the layout

Using a “pagration” in cases where an API may return a lot of data, it is a necessity, and if the load balance is not properly implemented, the service consumer may disappear. You should always keep in mind that the API design should take into account all possible scenarios.

In such cases, the use of Limit and Offset is recommended. For example you can do the following:

/products?limit=25&offset=50

This will also make you have a default and offset.

Supported formats

It is also important to choose the API response method. Most modern apps return JSON answers unless you have an old app that still needs an XML response.

Use appropriate error messages

It is always good to have a set of error messages that the app will send and receive with the right ID. For example, if you are using Facebook graphs API, it will issue a message as follows in the event of an error:

{
  "error": {
    "message": "(#803) Some of the aliases you requested do not exist: products",
    "type": "OAuthException",
    "code": 803,
    "fbtrace_id": "FOXX2AhLh80"
  }
}

There are also some examples in which people return a URL with an error message that provides more explanations about the error message as well as the method of managing it.

Use the features of OpenApi

In order for the teams to adhere to specific principles, the use of OpenAPI (+) characteristics can be appropriate. Openapi allows the basic design of the API and then subscribe to consumers in an easy way.

Final speech

So we come to the end of this article. Obviously, if you want to have better relationships, you should use APIs. But if the APIs are badly designed, they may increase confusion. So put your best effort to design them to have a simple implementation.

 

© 2022 Created with AloApi Team.