Rest Api Design Pdf



  1. Rest Api Design Pdf Download 3) HTTP methods (verbs) HTTP has defined few sets of methods which indicates the type of action to be performed on the resources. The URL is a sentence, where resources are nouns and HTTP methods are verbs. The important HTTP methods are as follows.
  2. In this book, we'll start by discussing the what an API is, why you might need one, and follow up with the how to build one. With addition of our Appendix on API Design Patterns and numerous other design tips, this book is complete. Regardless, we're always open to additional sections, concepts, and questions so don't hesitate to drop us a note.
  3. REST API’s should be designed for Resources, which can be entities or services, etc., therefore they must always be nouns. For example, instead of /createUser use /users 2.

A Guide to REST and API Design.

Rest Api Design Pdf Download

Book Name: REST API Design Rulebook
Author: Mark Masse
ISBN-10: 1449310508
Year: 2011
Pages: 116
Language: English
File size: 5.1 MB
File format: PDF

REST API Design Rulebook Book Description:

In today’s market, where rival web services compete for attention, a well-designed REST API is a must-have feature. This concise book presents a set of API design rules, drawn primarily from best practices that stick close to the Web’s REST architectural style. Along with rules for URI design and HTTP use, you’ll learn guidelines for media types and representational forms.

REST APIs are ubiquitous, but few of them follow a consistent design methodology. Using these simple rules, you will design web service APIs that adhere to recognized web standards. To assist you, author Mark Massé introduces the Web Resource Modeling Language (WRML), a conceptual framework he created for the design and implementation of REST APIs.

  • Learn design rules for addressing resources with URIs
  • Apply design principles to HTTP’s request methods and response status codes
  • Work with guidelines for conveying metadata through HTTP headers and media types
  • Get design tips to address the needs of client programs, including the special needs of browser-based JavaScript clients
  • Understand why REST APIs should be designed and configured, not coded
NOTICE:IF DOWNLOAD LINK IS BROKEN REPORT US AT [email protected]

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.

Identify Object Model

The very first step in designing a REST API based application is – identifying the objects which 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 sake, we will consider only two resources i.e.

  • Devices
  • Configurations

Rest Api Design Example

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.

Create Model URIs

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 its sub-resources. These resource URIs are endpoints for RESTful services.

In our application, a device is a top-level resource. And configuration is sub-resource under the device. Let’s write down the URIs.

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.

Api

Determine Representations

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.

Collection of Device Resource

When returning a collection resource, include only the most important information about resources. This will keep the size of payload small, and so will improve the performance of REST APIs.

Restful Api Design Matthias Biehl Pdf Github

Single Device Resource

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 HATEOAS driven.

Configuration Resource Collection

Rest Api Design Rulebook Pdf Github

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. Only difference is that configurations for a device are only two, so only two configuration items are listed as subresource under device.

Single Configuration Resource

Now, single configuration resource representation must have all possible information about this resource – including relevant links.

Configuration Resource Collection Under Single Device

This resource collection of configurations will be a subset of the 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 fields than primary collection. Use the same presentation fields as the primary collection.

Notice that this subresource collection has two links. One for its direct representation inside sub-collection i.e. /devices/12345/configurations/333443 and other pointing to its location in primary collection i.e. /configurations/333443.

Having two links is essential as you can provide access to a device- specific configuration in a more unique manner, and you will have the ability to mask some fields (if design requires it), which shall not be visible in a secondary collection.

Single Configuration Resource Under Single Device

This representation should have either exactly similar representation as of Configuration representation from the 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 the next section, let’s note down a 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.

Assign HTTP Methods

So our resource URIs and their representation are fixed now. Let’s decide the possible operations in the application and map these operations on resource URIs. A user of our network application can perform browse, create, update, or delete operations. So let’s assign them.

Browse all devices or configurations [Primary Collection]

If the collection size is large, you can apply paging and filtering as well. e.g., Below requests will fetch the first 20 records from collection.

Browse all devices or configurations [Secondary Collection]

It will be mostly a small size collection – so no need to enable filtering or soring here.

Rest Api Url Design

Browse single device or configuration [Primary Collection]

To get the complete detail of a device or configuration, use GET operation on singular resource URIs.

Browse single device or configuration [Secondary Collection]

Subresource representation will be either same as or a subset of primary presentation.

Create a device or configuration

Create is not idempotent operation, and in HTTP protocol – POST is also not idempotent. So use POST.

Please note that 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:

Update a device or configuration

Update operation is an idempotent operation and HTTP PUT is also is idempotent method. So we can use PUT method for update operations.

PUT response may look like this.

Remove a device or configuration

Removing is always a DELETE operation.

A successful response SHOULD be 202 (Accepted) if resource has been queues for deletion (async operation), or 200 (OK) / 204 (No Content) if 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.

Applying or Removing a configuration from a device

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 its idempotent nature.

More Actions

So far, we have designed only object models, URIs and then decided HTTP methods or operations on them. You need to work on other aspects of the application as well:

Rest Api Design Rulebook Pdf

1) Logging
2) Security
3) Discovery etc.

Rest Api Design Pdf Software

Rest

In the next article, we will create this application in java to get a more detailed understanding.