Basic RESTful API Guidelines
let's try it this way

REST stands for REpresentational State Transfer. REST is about software architectural style which can provide standards between networked systems over the internet, called web services, to communicate with each other. Generally speaking, web services that are built using the REST pradigm are known as RESTful web services. REST is considered ligthweight 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 the two basic concepts of REST.

1. 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 look at the case of a classic coffee shop. 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). See example below:

Example of a RESTful resource:

  • Menu
  • Utensil

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

  • getMenuInfo
  • getUtensilInfo

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:

[1. your_app_domain]/[2. collection_of_a_resource]/[3. optional_parameter]
  • The first segment of the URL gives us the information about the domain of our application, let's say it's myrestfulapp, thus we have:
  • 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.
  • Lastly, we use the optional parameter to allow consumer to manipulate specific resources by some keywords, such as get all menu priced exactly 5.00, or replace utensil number 10, etc. By looking at those illustrations, both of the services need an optional parameter in order to do the business. The first one needs price while the other needs ID, hence we have:{price}{id}

Here, the curly braces inform the service consumers that the service needs a parameter. Having those explanations, we'll go on the example of RESTful (REST-style) service endpoints.

Example of a RESTful service endpoints URL:

Example of a non-RESTful service endpoints (more like SOAP-style):

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

Nor these are example of a RESTful service endpoints URL (the collections are not nouns):

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:

2. REST is all about Representation

Tipically, REST uses JSON or XML to represent objects. For instance, let’s assume that a Menu has an ID, title and of course price. Here’s how a resource is represented in a RESTful web service.

  • Resource : Menu
  • Example Menu :
    • id : 1
    • title : Egg Benedict
    • price : 6.50
  • Representation using JSON :
	“id” : 1,
	“title” : “Egg Benedict”,
	“price” : 6.50

With the example above, we now get the point that using JSON a menu can be written as {“id” : 1, “title” : “Egg Benedict”, “price” : 6.50}. Let's take another example, we will assume that a Utensil has an ID, name and brief descriptions. Similarly, here’s how it should be represented in the REST-way.

  • Resource : Utensils
  • 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, used mainly for chopping and slicing, 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:

  • Status Code
    • HTTP provides a bunch of standardized codes which can be used to deliver various feedbacks.
  • Header
    • Contains the information about the server and about further access to the resource.
  • Body
    • This is where we will placed the resource representations.


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

Another Example:

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

In the above illustration, the request is successfully handled by the server in the first example, giving the 200 status code while giving the 404 status code ont the other example because we does not serve a resource named getMenus. The response also indicates that it has JSON in its body. As we can see, the response body 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.

These guidelines are based on my own experience. I would love hearing your views and opinions. Please leave a comment, and let me know!

Image Source:*uHzooF1EtgcKn9_XiSST4w.png

Written by gpamungkas on May 21 2019, 11:20 AM.