https://cdn-images-1.medium.com/max/1600/1*uHzooF1EtgcKn9_XiSST4w.png

Basic RESTful API Guidelines

Did I hear API?

REST stands for REpresentational State Transfer. REST is all about software architectural style which can provide a standard between networked systems over the internet, called web services, to communicate with each other.

Generally speaking, web services that are built using the REST paradigm are known as RESTful web services. REST is considered lightweight yet powerful. It doesn’t create any new standards, but instead uses the existing prominent standards such as HTTP, JSON and XML.

In order to understand deeper, we would like to touch upon very basic concepts of REST.

REST is Resource-Based

REST emphasizes on resource, which is an object to be manipulated. A resource is defined by nouns not verbs. To give an illustration, let’s take a look at the case of a classic restaurant.

Apparently, it has a list of menu and sets of kitchen utensils. We will now think them as the identified objects, that is to say, the resources.

Using the gathered resources, we are going to define the RESTful service endpoints which then allow consumers to manipulate the resources (e.g. get menu information, update the menu information, replace kitchen utensils, etc).

Example of a RESTful resource (nouns):

• Menu
• Utensil

Example of a non-RESTful resource (verbs, more like SOAP-style):

• getMenuInfo
• getUtensilInfo

The Endpoints

RESTful service endpoints are identified by URL (Uniform Resource Locator) which is simply a representation of a resource, where it is located and how to manipulate it. On this example, we will use the pattern below:

[your_app_domain]/[resources_name]/[optional_parameter]

The first segment of the URL gives us the information about the domain of your application, let’s say it’s myrestfulapp, thus we have:

http://myrestfulapp.com

The second one is literally about collections of a resource. In this case, we have indicated two resource : menu and utensil, hence we have two collections which will be simply named menus and utensils.

http://myrestfulapp.com/menus

and

http://myrestfulapp.com/utensils

Lastly, we use the optional parameter to allow consumer to manipulate specific resources by a value, for example: get all menu having the price exactly 5.00.

For the above case, then we need to define the price as the parameter. Hence we have:

http://myrestfulapp.com/menus/{price}

Here, the curly braces tell us that the service needs a parameter. So if we want to get all menu having the price exactly 5.00, the URL should be:

http://myrestfulapp.com/menus/500

Having those explanations, we are now able to consider these example as RESTful services:

• http://myrestfulapp.com/menus/{id}
• http://myrestfulapp.com/utensils/{id}

And these are the examples of non-RESTful service endpoints (more like SOAP-style):

• restaurantAPI.getMenuInfo(int id)
• restaurantAPI.getUtensilInfo(int id)

Nor these are examples of RESTful service endpoints URL (since the collections are not nouns):

• http://myrestfulapp.com/getMenuInfo/{id}
• http://myrestfulapp.com/getUtensilInfo/{id}

HTTP Methods

RESTful service endpoints use HTTP methods (POST, GET, PUT and DELETE) to specify which action a service consumers want to manipulate the resources.

Example of a RESTful service endpoints with a GET method:

GET http://myrestfulapp.com/menus

This would mean that we want to get all menus available.

Another example:

GET http://myrestfulapp.com/menus/{id}

This would mean we want to get the details of a specific menu which is identified by such id

Another example using DELETE method:

DELETE http://myrestfulapp.com/menus/{id}

Using this service, you ask your app to remove a specific menu identified by such id.

REST is all about Representation

Tipically, REST uses JSON or XML to represent objects. For instance, let’s assume that a Menu has this information: ID, title and price.

Here’s how a resource is represented in a RESTful web service.

Example Menu:

• id : 1
• title : Egg Benedict
• price : 6.50

Its representation using JSON will be:

{
	“id” : 1,
	“title” : “Egg Benedict”,
	“price” : 6.50
}

Let’s take another example, we will assume that a Utensil has this information: ID, name and brief descriptions.

Similarly, here’s how it should be represented in the REST-way.

Example Utensil:

• id : 10
• name : Chef Knife
• desc : A general purpose knife, used mainly for chopping and slicing, suitable for vegetables and meats

Representation using JSON:

{
	“id” : 10,
	“name” : “Chef Knife”,
	“desc” : “A general purpose knife suitable for vegetables and meats”
}

Packing up a Response

When a service consumer makes a request to the service endpoints, the server should respond with a legitimate feedback, that is to say, whether the server failed to handle the request, the request is not valid or the request is just handled properly.

Since RESTful web services use HTTP, it should also response in the HTTP-way. HTTP response consists mainly of three parts:

1. Status Code

HTTP provides a bunch of standardized codes which can be used to deliver various feedbacks (500, 404, 200, etc).

2. Header

Contains the information about the server and about further access to the resource.

3. Body

This is where we will placed the resource representations.

For the example

The request:

GET http://myrestfulapp.com/menus/1

The response:

• Status Code: HTTP 1.1. 200 OK
• Header: Content-Type: application/json
• Body :

{
	“status” : 1,
	“message” : “menu exists, the information has been successfully retrieved.”,
	“data” : “{“id” : 1, “title” : “Egg Benedict”, “price” : 6.50}”
}

Another Example:

The request:

GET http://myrestfulapp.com/getMenus/1

The response :

• Status Code : HTTP 1.1. 404 Not Found
• Header : Content-Type: application/json
• Body :

{
	“status” : 0,
	“message” : “the requested resource could not be found but may be available in the future.”,
	“data” : null
}

Explanation

In the above illustration, the request is successfully handled by the server in the first example, thus giving the 200 status code.

The second request however, it gives the 404 status code since we do not serve a resource named getMenus.

The response also indicates that it has JSON in its body which is represented in 3 parts, which are: status, message, and data.

Seeing that we have a well-executed request/response scheme, the server gives the status 1, otherwise it gives 0. The message contains additional information about the transaction and obviously the last part of the body encloses the representation of the corresponding resources.

Last Words

So this is it, I hope it would be helpful especially if you have just started to learn to code. Those guidelines are based on my own experience. Hence I would love to hear any thoughts.

Please leave a comment, and let me know!

modified from the post: https://blog-tki.universitaspertamina.ac.id/post/18