rest api design

RESTFul Design – REST API Design Best Practices

Resul Bozburun Programming

RESTful design is one of the most important parts of creating an app. API (Application Programming Interface), provides a communication interface for two applications. So, designing and applying RESTful best practices is a major key to application development.

Using API makes easier the development stages. For example, to program a discord bot we’ve used Discord’s API.

 

What is API?

rest api design

Application Programming Interface is a layer that provides communication ease for web apps, mobile apps, or desktop apps. For example, we’ve used API when using WhatsApp. When you send a message or share a story, WhatsApp mobile application sends or fetches data with/to API.

 

What are REST and RESTful? What is the Difference?

REST is a short form of Representational State Transfer. It is used for creating web services programming language independently. REST uses HTTP protocol to reply to requests to get JSON or XML data. Services that use REST architecture are called RESTful services. So, RESTful API means API that uses REST architecture. As we talked about the “difference between rest and restful” now, let’s explain restful design approaches for best practices.

 

RESTFul Design – RESTful API Design Best Practices

RESTful best practices include 5 steps:

  • Modeling of resources
  • Creating model URIs
  • Representation
  • HTTP Methods Declaration
  • Optional steps include logging, security mechanisms, etc.

 

Modeling of Resources

Modeling resources for REST API design is the initial part of creating a web API. First resources should be determined. For example, if you want to create a school API you should make your resources. There are some resource examples:

students
teachers
classes

 

Creating Model URIs

After determining the resource, the model URIs should be created for resources. According to the RESTful best practices a proper URI must be clear and understandable when you look at it. For example for our school API, we can create model URIs like the below.

/students
/students/id/1
/teachers
/teachers/id/1
/classes
/classes/id/1
/teacher/id/1/classes
/students/id/1/teachers
/students/id/1/class

 

Representation

For a proper RESTful design, the model URIs should return a JSON or XML representation of resources. For example, in our case, the “GET /students” returns the following representation.

HTTP/1.1 200 OK
Content-Type: application/json

"data" : [
	{
	    "id":"1",
	    "name": "john doe",
			"class":"1-b",
			"teachers": "1,2,4"
	
	},
	{
	    "id":"2",
	    "name": "marry jane",
			"class":"2-b",
			"teachers": "1,2"
	
	},
	{
	    "id":"3",
	    "name": "tyler durden",
			"class":"1-a",
			"teachers": "1,2,5"
	
	},
]

 

HTTP Method Declaration

Since we’ve used RESTful API design architecture in this tutorial, our API serves on layer 7 and uses HTTP protocol. So, we should use HTTP methods to communicate with the server that hosts API.

  • GET: Returns 200 OK or 404 Not found. Collects data about specified resource URI from the API endpoint. The body of the response contains details about the resource that is requested.
  • POST: Returns 200 OK, 201 Created, or 204 No Content. Creates a new resource. The body of the request must include details about the resource that wants to be created. Also, it can be used to trigger resources.
  • PUT: Returns 200 OK, 201 Created, or 204 No Content. Creates or replaces the resource for specified URI. The body of the requests includes details about the resource to want to be created or replaced.
  • PATCH: Returns 200 OK or 204 No Content. Provides updates for the specified resource. The resource must be specified in the request body.
  • DELETE: Returns 200 OK or 202 Accepted (for async calls) or 204 No Content. Removes the specified resource.

 

Optional Steps

According to the RESTful API best practices, authentication for security, and debugging for logging must be implemented. Also a well-designed REST API, all endpoints of the API should be discoverable. The API should be detailed and documented.

 

REST API Status Codes (Summary)

  • 200 OK: Successful request.
  • 201 Created: Successful request and the object created.
  • 202 Accepted: Successful request but not completed. (Async)
  • 204 No Content: Successful request but the response is not necessary. The request has already proceeded.
  • 404 Not Found: Request failed, resource not found.

 

Asynchronism

To make asynchronous calls the API developer should create endpoints that must return 202 Accepted status code. To learn the status you can make a GET request to the async endpoints. According to the RESTful API best practices, the async requests return a response like the below.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status":"In progress",
    "obj": { "method":"delete", "objref":"/apiv1/status/11" }
}

After the async request is successfully done, the endpoint returns 303 See Other and provides the link to the new resource.

For an excellent RESTful design, also you can use filtering and pagination techniques if you have a lot of data. The web API is responsible to parse URI parameters like the below.

/students?size=25&page=1

Leave a Reply