Unparalleled suite of productivity-boosting Web APIs & cloud-based micro-service applications for developers and companies of any size.


Advanced REST API Design

Web Design

Rest is a data transfer method used in software built on service-oriented architecture. It runs on HTTP and is simpler than other alternatives, and faster because it sends and receives data with minimal content. It enables applications to communicate by carrying XML or JSON data between client and server.

Rest lightweight and stateless has increased its use and popularity today. Rest Services are offered or consumed in almost every application so that they can communicate with each other. So what are the best practices when creating these services? So, let’s take a look at what are the advanced best practices while developing the Rest API.


API versioning

API versioning is as important as the security and code quality of our API layer. Because managing the requirements of the applications we have developed by versioning will provide us with a comfortable development area at many points and if we are doing documentation, it will be a good guide for the end users we serve.

Versioning has an essentially spatial need rather than traditional influences. This need is basically about the client-server relationship on physical updates in APIs. Changes made in APIs used by certain consumers will cause breakages/explosions for existing consumers. Therefore, the first factor to be considered in a change is the interruptions that may occur in the functional flows of those API consumers. In such a case, it is very useful to define the way clients interact with the API.

After the client’s relationship with the API and the data format structuring, if we come to the main question, ‘Why Do We Need to Version the APIs?’; As a result of each change made in an API, we need to inform the relevant client in order not to damage the relationship between the API and the client consuming that API. Here, versioning provides a sufficiently effective solution and informs the client as a result of only a small arithmetic operation on a numerical value in the url and allows the wheel to continue from where it left off.

In addition, versioning is carried out to report the changes made in the API and to emphasize the up-to-dateness of the API with reference to the latest change.


HTTP response code

Rest APIs in your application should inform the client according to the operations they perform. The HHTP status codes to be used while doing this have become a standard. For example, if you have successfully added a Rest API that adds a product to your application, the client should return the HTTP 201 status code as a response. Sometimes undesirable situations may occur in your application. Exception or error conditions. In such cases, the relevant HTTP code should be preferred.

You can take a look at the most commonly used HTTP status code list below when developing the Rest API.

  • 200 OK – The status code returned after a successful GET, PUT, PATCH or DELETE operation. It can be used in POST if it is not sent for record creation (as it usually should).
  • 201 Created – Status code used in successful responses returned to a POST request for a create operation.
  • 204 No Content – Can be used for a successful response that does not need to return a content. You can use the example if a DELETE request was successful and there is no need to return a message.
  • 400 Bad Request – You can use this code if there is a problem with the request made, for example if the parameters that need to be sent are not sent.
  • 401 Unauthorized – Use if incorrect user cookies or no information was sent.
  • 403 Forbidden – It is the error code used in cases where the user, which is often confused with / replaced with 401, is not recognized, but is not authorized.
  • 404 Not Found – Almost the most common error code. This code is returned if the requested resource does not exist on the server.
  • 405 Method Not Allowed – Used if the method used when sending the request is not supported for the logged in user.
  • 422 Unprocessable Entity – It is used when validation cannot be performed in situations that require validation (For example, if we are going to return the error that the user name must be at least 8 characters).
  • 429 Too Many Request – Rate limit – Used to indicate if the request limit has been exceeded.
  • 500 Internal Server Error – Most of the time, this error happens out of our control, but if we set up a low-level error management structure to handle it, it will be useful for us to show it to the user and keep a proper log.

Resource Modeling Rules

The implementation of Resource Modeling, which is often preferred when developing a Rest API, makes the URI more readable and meaningful.

Document and store names must be singular.



Collection names must be plural



Controller names must be verbs



It is a good practice to use path variables as ID when expressing Documents and Stores as it will reduce the load on the servers.




HTTP Methods

Now let’s move on to the rules about using HTTP methods in REST. The standards of the HTTP protocol are written in RFC 2616(link: https://www.ietf.org/rfc/rfc2616.txt).

HTTP Method


The GET method is used to fetch the resource specified in the URI. There is no body in this request. It’s just the header.


curl -XGET ‘https://jsonplaceholder.typicode.com/todos/1’

We get the following JSON representation in response to the request we send without adding a header or body.



  “userId”: 1,

  “id”: 1,

  “title”: “delectus aut autem”,

  “completed”: false




The only difference of the HEAD method from the GET method is that it does not send a body in the response. We make this request for the headers that will be sent in the response. For example, it can be used to check if a resource is in the specified URI or to see when the resource was last modified (Last-Modified).

curl –head ‘https://jsonplaceholder.typicode.com/todos/1’

Since we are sending a request with the HEAD method, there will be no body in the incoming response. But we can see the headers.



We use the POST method to create a new resource on the server we send the request, to run the controller resources and to send the form inputs. Since we will send data for all these operations, we send the body while using the POST method.


curl -X POST https://jsonplaceholder.typicode.com/posts\

  -D ‘{

          “title”: “Foo”,

          “body”: “Bar”


In response, we get the information of the post we created.



    “title”: “Foo”,

    “body”: “Bar”,

    “id”: 101




As the name suggests, it is the request sent to delete the resource specified in the URI. It is only used to delete the relevant resource and never be accessed again. If soft-delete is to be made, an application-specific controller is defined for this.



We use it to find out which methods the URI to which we are sending a request supports. This information is given to us with allow in the header.



The PATCH method is similar to PUT, but it is used if the resource is to be partially updated. For example, if only the title of a blog post will be updated, it would be a more cost-effective choice to send the title in the body with the PATCH method.



For Rest APIs developed in applications, advanced best practice, consistent and understandable web services can be developed by using the design methods mentioned in the article.


Related posts

HTML to PDF API Tutorial: Generating Invoices and Receipts with PDFLayer and VATLayer APIs


API Marketplace vs API Gateway: What’s the Difference?


How to Use the ScreenshotLayer and PDFLayer APIs to Create a Web Page Archiver


What Are API Keys? (And Are They Secure?)

Leave a Reply

Your email address will not be published. Required fields are marked *