REST API basic tutorial

 
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 application’s architecture from the very start – it surely has a great impact on how the app is going to work after it’s 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.

What is REST?

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

If your service follows all those 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 more in-depth look at them.

Uniform interface

 
REST architecture implies 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 an application into multiple ones.

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

REST 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 being transferred between clients and servers has to be converted to 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, per 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

 
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 uniform interface)

• Interaction transparency. Because of its standardization, API remains easily understandable for 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 HTTP methods and their possible responses.

HTTP status codes

 
It is important to use 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:

1. 200 OK
2. 201 Created
3. 204 No Content
4. 304 Not modified
5. 400 Bad request
6. 401 Unauthorized
7. 403 Forbidden
8. 404 Not found
9. 409 Conflict
10. 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 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 Smartum Pro, we provide professional consultancy services and we’ll be glad to help you with the implementation of your great ideas!