Last updated
Last updated
The following is from:
REST is acronym forREpresentationalStateTransfer. It is architectural style fordistributed hypermedia systemsand was first presented by Roy Fielding in 2000 in his famous.
Like any other architectural style, REST also does have it’s ownwhich must be satisfied if an interface needs to be referred asRESTful. These principles are listed below.
Client–server
– By separating the user interface concerns from the data storage concerns, we improve the portability of the user interface across multiple platforms and improve scalability by simplifying the server components.
Stateless
– Each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client.
Cacheable
– Cache constraints require that the data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable. If a response is cacheable, then a client cache is given the right to reuse that response data for later, equivalent requests.
Uniform interface
– By applying the software engineering principle of generality to the component interface, the overall system architecture is simplified and the visibility of interactions is improved. In order to obtain a uniform interface, multiple architectural constraints are needed to guide the behavior of components. REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state.
Layered system
– The layered system style allows an architecture to be composed of hierarchical layers by constraining component behavior such that each component cannot “see” beyond the immediate layer with which they are interacting.
Code on demand (optional)
– REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts. This simplifies clients by reducing the number of features required to be pre-implemented.
The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service, a collection of other resources, a non-virtual object (e.g. a person), and so on. REST uses a resource identifier to identify the particular resource involved in an interaction between components.
The state of resource at any particular timestamp is known as resource representation. A representation consists of data, metadata describing the data and hypermedia links which can help the clients in transition to next desired state.
Other important thing associated with REST is resource methods to be used to perform the desired transition. A large number of people wrongly relate resource methods to HTTP GET/PUT/POST/DELETE methods.
A lot of people prefer to compare HTTP with REST.REST and HTTP are not same.
Learning REST in pieces is one thing, while applying all those learned concepts into real application design is completely another challenge. In this tutorial, we will learn to design REST APIs for a network based application. Please note that the takeaway from this whole exercise is the learning of how to apply REST principles in design process.
Steps in designing REST Services
Identify Object Model Create Model URIs Determine Representations Assign HTTP Methods More Actions
The very first step in designing a REST API based application is – identifying the objects which will be presented as resources.
Example
For a network based application, object modeling is pretty much simpler. There can be many things such as devices, managed entities, routers, modems etc. For simplicity sake, we will consider only two resources i.e.
Devices
Configurations
Here configuration is sub-resource of a device. A device can have many configuration options.
Note that both objects/resources in our above model will have a unique identifier, which is the integer id property.
Now when object model is ready, it’s time to decide the resource URIs. At this step, while designing the resource URIs – focus on the relationship between resources and its sub-resources. These resource URIs are endpoints for RESTful services.
Example
In our application, a device is a top-level resource. And configuration is sub-resource under device. Let’s write down the URIs.
Notice that these URIs do not use any verb or operation. It’s very important to not include any verb in URIs. URIs should all be nouns only.
Now when resource URIs have been decided, let’s work on their representations. Mostly representations are defined in either XML or JSON format. We will see XML examples as its more expressive on how data is composed.
When returning a collection resource, include only most important information about resource. This will keep the size of payload small, and so will improve the performance of REST APIs.
Similar to device collection representation, create configuration collection representation with only minimal information.
Please note thatconfigurationscollection representation insidedeviceis similar to top-levelconfigurationsURI. Only difference is thatconfigurationsfor a device are only two, so only two configuration items are listed as subresource under device.
Now, single configuration resource representation must have all possible information about this resource – including relevant links.
This resource collection of configurations will be a subset of primary collection of configurations, and will be specific a device only. As it is the subset of primary collection,DO NOT create a different representation data fieldsthan primary collection. Use same presentation fields as primary collection.
Notice that this subresource collection has two links. One for its direct representation inside sub-collection i.e./devices/12345/configurations/333443and other pointing to its location in primary collection i.e./configurations/333443.
Having two links is important as you can provide access to a device specific configuration in more unique manner, and you will have ability to mask some fields (if design require it) which shall not be visible in a secondary collection.
This representation should have either exactly similar representation as of Configuration representation from primary collection; OR you may mask few fields.
This subresource representation will also have an additional link to its primary presentation.
Now, before moving forward to next section, let’s note down few observations so you don’t miss them.
Resource URIs are all nouns.
URIs are usually in two forms – collection of resources and singular resource.
Collection may be in two forms primary collection and secondary collection. Secondary collection is sub-collection from a primary collection only.
Each resource/collection contain at least one link i.e. to itself.
Collections contain only most important information about resources.
To get complete information about a resource, you need to access through its specific resource URI only.
Representations can have extra links (i.e. methods in single device). Here
method
represent a POST method. You can have more attributes or form links in altogether new way also.
We have not talked about operations on these resources yet.
So our resource URIs and their representation are fixed now. Let’s decide the possible operations in application and map these operations on resource URIs. A user of network application can perform browse, create, update or delete operations. So let’s map them.
If the collection size is large, you can apply paging and filtering as well. e.g. Below requests will fetch first 20 records from collection.
It will be mostly a small size collection – so no need to enable filtering or soring here.
To get the complete detail of a device or configuration, useGEToperation on singular resource URIs.
Subresource representation will be either same as or subset of primary presentation.
Please note that request payload will not contain anyidattribute, as server is responsible for deciding it. Response of create request will look like this:
Update operation is an idempotent operation and HTTPPUTis also is idempotent method. So we can use PUT method for update operations.
PUT response may look like this.
Removing is always aDELETEoperation.
A successful response SHOULD be202 (Accepted)if resource has been queues for deletion (async operation), or200 (OK)/204 (No Content)if resource has been deleted permanently (sync operation).
In case of async operation, application shall return a task id which can be tracked for success/failure status.
Please note that you should put enough analysis in deciding the behavior when a subresource is deleted from system. Normally, you may want to SOFT DELETE a resource in these requests – in other words, set their status INACTIVE. By following this approach, you will not need to find and remove its references from other places as well.
In real application, you will need to apply the configuration on device – OR you may want to remove the configuration from device (not from primary collection). You shall use PUT and DELETE methods in this case, because of its idempotent nature.
So far we have designed only object model, URIs and then decided HTTP methods or operations on them. You need to work on other aspects of the application as well:
The data format of a representation is known as a. The media type identifies a specification that defines how a representation is to be processed.A truly RESTful API looks likehypertext. Every addressable unit of information carries an address, either explicitly (e.g., link and id attributes) or implicitly (e.g., derived from the media type definition and representation structure).
Opposite to collection URI, here include complete information of a device in this URI. Here, also include a list of links for sub-resources and other supported operations. This will make your REST API driven.
Create is notoperation, and in HTTP protocol –POSTis also not idempotent. So use POST.
1) Logging 2) 3) Discovery etc.
HTTP GET /devicesHTTP GET /configurations
HTTP GET /devices?startIndex=0&size=20HTTP GET /configurations?startIndex=0&size=20
HTTP GET /devices/{id}/configurations
HTTP GET /devices/{id}HTTP GET /configurations/{id}
HTTP GET /devices/{id}/configurations/{id}
HTTP POST /devicesHTTP POST /configurations
HTTP/1.1 201 CreatedContent-Type: application/xmlLocation:http://example.com/network-app/configurations/678678<configurationid="678678"><linkrel="self"href="/configurations/678678"/><content><![CDATA[...]]></content><status>active</status><linkrel="raw configuration content"href="/configurations/678678/raw"/></configuration>
HTTP PUT /devices/{id}HTTP PUT /configurations/{id}
HTTP/1.1 200 OKContent-Type: application/xml<configurationid="678678"><linkrel="self"href="/configurations/678678"/><content><![CDATA[. updated content here .]]></content><status>active</status><linkrel="raw configuration content"href="/configurations/678678/raw"/></configuration>
HTTP DELETE /devices/{id}HTTP DELETE /configurations/{id}
//Apply Configuration on a deviceHTTP PUT /devices/{id}/configurations //Remove Configuration on a device HTTP DELETE /devices/{id}/configurations/{id}