Follow these steps to design a REST API – Identify Object Model, Create Resource URIs, Determine Representations and Assign HTTP Methods.
Written by: Lokesh Gupta
Last Updated: November 6, 2023
Learning REST in pieces is one thing while applying all these concepts to real application development is completely another challenge.
This tutorial will teach us to design REST APIs for a network-based application. Please note that the takeaway from this whole exercise is learning how to apply REST principles in the application design process.
The first step in designing a REST API-based application is identifying the objects that will be presented as resources.
For a network-based application, object modeling is pretty much more straightforward. There can be many things such as devices, managed entities, routers, modems, etc. For simplicity’s sake, we will consider only two resources i.e.
Here configuration may be a 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 the 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 their sub-resources. These resource URIs are endpoints for APIs.
In our application, a device is a top-level resource. And, configuration is a sub-resource under the device. Let’s write down the URIs.
/devices /devices/ /configurations /configurations/ /devices//configurations /devices//configurations/
Notice that these URIs do not use any verb or operation. It’s crucial not to include any verb in URIs. URIs should all be nouns only.
Now that resource URIs have been decided, let’s work on their representations. Most representations are defined in either XML or JSON format. We will see XML examples as it is more expressive of how data is composed.
When returning a collection resource, include only the most important information about that resource. This will keep the size of the response payload small, and so will improve the performance of the API.
apple-es 10.3R2.11 SRX100B 32423457 up 192.168.21.9 apple-srx_200 active apple-es 10.3R2.11 SRX100B 6453534 up 192.168.20.23 apple-srx_200 active Opposite to collection URI, a single resource URI includes complete information about a particular device. It also includes a list of links to sub-resources and other supported operations. This will make your REST API HATEOAS driven.
12345 apple-es 10.0R2.10 SRX100-LM 32423457 apple-srx_100_lehar apple-srx_100_lehar 192.168.21.9 active Similar to device collection representation, create configuration collection representation with only minimal information.
Please note that configurations collection representation inside device is similar to top-level configurations URI.
The only difference is that configurations for a device are only two, so only two configuration items are listed as subresources under the device.
Now, a single configuration resource representation must have all possible information about this resource – including relevant links.
active This sub-collection of configurations will be a subset of the primary collection of configurations and will be specific to a device only.
As it is the subset of primary collection, DO NOT create a different representation data field than primary collection. Use the same presentation fields as the primary collection.
Notice that this sub-resource collection has two links. One for its direct representation inside sub-collection i.e. /devices/12345/configurations/333443 and others pointing to its location in the primary collection i.e. /configurations/333443 .
Having two links is essential as you can provide access to a device-specific configuration more uniquely, and you will be able to mask some fields (if the design requires it), which shall not be visible in a secondary collection.
This representation should have either exactly a similar representation as of Configuration representation from the primary collection, OR you may mask a few fields.
This subresource representation will also have an additional link to its primary presentation.
active Now, before moving forward to the next section, let’s note down a few observations, so you don’t miss them.
So our resource URIs and their representation are fixed now. Let’s decide all the applications’ possible operations and map those operations to the resource URIs.
For example, a user of our network application can browse, create, update, or delete devices from the network and create/deploy/remove the device configurations. So let’s assign these operations to respective resources.
HTTP GET /devices HTTP GET /configurationsIf the collection size is large, you can also apply paging and filtering. e.g., the below requests will fetch the first 20 records from the collection.
HTTP GET /devices?startIndex=0&size=20 HTTP GET /configurations?startIndex=0&size=20HTTP GET /devices//configurationsIt will be mostly a small-size collection, so there is no need to enable filtering or sorting here.
To get the complete detail of a device or configuration, use GET operation on singular resource URIs.
HTTP GET /devices/ HTTP GET /configurations/
HTTP GET /devices//configurations/
Subresource representation will be either same as or a subset of the primary presentation.
CREATE is not an idempotent operation and in HTTP protocol – POST is also not idempotent. So use POST.
HTTP POST /devices HTTP POST /configurationsPlease note that the request payload will not contain any id attribute, as the server is responsible for deciding it. The response to CREATE request will look like this:
HTTP/1.1 201 Created Content-Type: application/xml Location: http://example.com/network-app/configurations/678678 active The update operation is an idempotent operation, and HTTP PUT is also an idempotent method. So we can use the PUT method for update operations.
HTTP PUT /devices/ HTTP PUT /configurations/
PUT response may look like this.
HTTP/1.1 200 OK Content-Type: application/xml active Removing is always a DELETE operation.
HTTP DELETE /devices/ HTTP DELETE /configurations/
A successful response SHOULD be 202 (Accepted) if the resource has been queued for deletion (async operation), or 200 (OK) / 204 (No Content) if the resource has been deleted permanently (sync operation).
In the case of async operation, the application shall return a task id that 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 the system. Usually, 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 a real application, you will need to apply the configuration on the device – OR you may want to remove the configuration from the device (not from the primary collection). You shall use PUT and DELETE methods in this case, because of their idempotent nature.
//Apply Configuration on a device HTTP PUT /devices//configurations //Remove Configuration on a device HTTP DELETE /devices//configurations/
So far, we have designed only object models, and URIs and then decided on HTTP methods or operations on them. You need to work on other aspects of the application as well:
