REST API basic tutorial: main characteristics and advantages

When developing a web-service, there are always many points to be considered by the product owner and the development team. The product owner provides his team with project requirements so the team knows exactly what to do.

Depending on goals and requirements you should choose the application’s architecture from the very start – it surely has a great impact on how the app is going to work after its release. Today we will talk about one of the most popular architecture types – REST.

You can get the most basic understanding of REST conception in Ryan Tomayko’s post called “How I explained REST to my wife”. But if you want to know more about technical details, you can learn more in our article. Let’s begin with our little REST API tutorial.

 

What is REST API?

 

Representational state transfer is an architectural style that is used for web services development. There are 6 rules that need to be followed when developing a product.

If your service follows all these rules, then it can be called a RESTful service. In addition, REST requires your project to use most of HTTP protocol’s features.

 

So, what are the REST rules?

• Uniform interface;
• Stateless;
• Cacheable;
• Client-server;
• Layered System;
• Code on demand.

 Let’s have a more in-depth look at them.

 

Uniform interface

REST architecture implies the usage of a uniform interface for all client-server interactions. While using REST, the client is interacting with the server to get resources and to manipulate them.

For example, tables can be considered as a resource, though it is not always possible (in cases when queries have a complex logic of interaction with resources).

The interface itself has to use different URLs while working with various resources. Proper separation of queries can be used to split one application into multiple ones.

It significantly increases the project’s portability and scalability. In addition, that makes it easier for developers to understand API (even if there is no detailed documentation).

REST API implementation also requires to use only plural nouns for resource’s names. You should not overload the system with multiple URLs. Each resource should only have 2 URLs in most of the common cases.

For instance:

• To retrieve a collection of elements: /buildings
• To retrieve an element by its ID: /buildings/{id}

The information that is being transferred between clients and servers has to be converted to the appropriate transferring format. JSON or XML, for instance, though JSON is the most popular at the moment.

Nevertheless, there are some web-services that support simultaneous work with multiple formats. Both formats (of returned and processed data) have to be controlled by HTTP-headers – Accept and Content-type.

HTTP header provides various information about the request or response, or, let’s say, about the object sent in the message body. For example: application/json or application/xml.

 

Stateless 

RESTful service’s query has to identify itself with a resource or resources while controlling their full state. RESTful web-services should not store any data regarding queries or cookies.

 

Cacheable 

Clients should be able to cache queries. Responses should define themselves as cacheable or not (implicitly or explicitly), to prevent any clients from re-using outdated or even inappropriate data in response to further requests.

Well-managed caching can partially (or even completely) eliminate some of the client-server interactions, which helps to improve overall scalability and performance. 

 

Client-server 

A uniform interface has to separate clients from servers. This implies the separation of their responsibilities (the interface should work independently from both client and server). For example:

• Clients should know nothing about the data stored on servers because it’s server’s zone of responsibility.
• Servers are not concerned with the UI or user state so that they can be simpler and more scalable.

 

Layered System 

The system can have intermediary servers so the client won’t know exactly which server he is interacting with. Intermediary servers can also decrease server load acting as load balancers and providing shared caches. 

 

Code on demand 

Any REST API tutorial will say that this is an optional rule. Servers can temporarily customize or modify the functionality of any client by transferring its executable code (Javascript).

 

Why REST?

 

Despite the fact that REST can be used in every HTTP-based product, sometimes its implementation is impossible because of lack of experience.  But if your team is skillful enough for REST implementation, your project can get lots of advantages: 

• Better overall performance. REST returns only the data that was specified in the query. This allows to speed up both query and response processing;
• Scalability. Service can be deployed on multiple servers and this helps to balance server load between them. Also, you can split your service into multiple simultaneously running “microservices”;
• Portability (thanks to the uniform interface);
• Interaction transparency. Because of its standardization, API remains easily understandable for the user;
• Ease of change. Thanks to lesser code dependency it’s much more difficult to break something when modifying different app parts.

 

HTTP methods

 

HTTP contains 4 methods: GET, POST, PUT, DELETE. Each method should be used for specific tasks. It should identify the functionality provided with a query. 

• GET. Use it to get resources (resource list or single resource by its id);
• POST. Use it to create resources;
• PUT. Use it to update resources by id (which is transferred via URL);
• DELETE. Use it to delete resources by id.

 We’ve made up a little table for your convenience. This table contains all of the HTTP methods and their possible responses.

HTTP status codes

 

It is important to use the right status codes for certain server responses. HTTP has several dozens of various status codes, but we are going to list only the most popular ones:

• 200 OK;
• 201 Created;
• 204 No Content;
• 304 Not modified;
• 400 Bad request;
• 401 Unauthorized;
• 403 Forbidden;
• 404 Not found;
• 409 Conflict;
• 500 Internal Server error.

 

HTTP has plenty of various error codes, but still, it’s not enough for any application out there. But it’s possible to insert an additional message into response body to clarify the issue (via json, xml, etc.).

 

 

Additional REST tips 

 

• Queries that return collections of elements should also have pagination, sorting and filtration features;
• Date and time should be using unix timestamp format (in milliseconds);
• Application version should be encoded in the app’s URL via node. For example, api.app.com/v1/buldings.

 

Feel free to contact us via quote form if you have any questions left. Here at Smartym Pro, we provide professional consultancy services as well as custom web development services and we’ll be glad to help you with the implementation of your great ideas!