The Fundamentals of REST API Design - Stormpath User Identity API

Here at Stormpath, we give developers easy access to user management features – including authentication, authorization, and password reset – via our REST API and language-specific SDKs. Our team of experts began with already-significant knowledge about REST+JSON API design. In the process of building the REST API, they learned even more. Our CTO, Les Hazelwood, gave a well-received presentation to a group of Java developers on REST+JSON API design best practices, which you can watch here:

We’ve also written posts on how best to secure your REST API, as well as linking and resource expansion in REST APIs. This post will give a high level summary of the key points that Les touches on in his talk – specifically the fundamentals of good REST+JSON API design.

So Why REST?

Keeping the goal of rapid adoption of an API in mind, what makes RESTful APIs so appealing? Per Dr. Roy Fielding’s thesis on the REST paradigm, there are 6 distinct advantages of REST:

Scalability – not necessarily its performance, yet rather how easy it is for RESTful APIs to adapt and grow and be plugged into other systems.
Use of HTTP – being able to use HTTP methods to manage resources makes RESTful APIs easy to plug into other applications.
Independency – with a REST API you can deploy or scale down specific parts of the application, without having to shut down the entire application or an entire web server form.
Reduced latency due to caching – REST APIs prioritize caching, which helps to improve latency. So always keep caching top of mind when you’re developing your REST API.
Security – HTTP specification lets you sport security via certain HTTP headers, so you can leverage this to make your API secure.
Encapsulation – there are parts of the application that don’t need to be exposed to a REST caller, and REST as an architectural style allows you to encapsulate those gritty details and only show things that you need to show.

And Why JSON?

Ubiquity – over 57 percent of all web-based applications have JSON, are built on JavaScript, or have JavaScript components.
Human readable – it uses very simple grammar and language, so a human can easily read it, including folks just starting to get into software development.
It’s easy to change or add new fields.

What makes REST design difficult?

RESTful APIs are difficult to design because REST is an architectural style, and not a specification. It has no standard governing body and therefore has no hard and fast design rules. What REST does have is an interpretation of how HTTP protocol works, which allows for lots of different approaches for designing a REST API. While use of HTTP methods is a core advantage of the REST approach, it also means that there are lots of different RESTful API designs. We’re going to focus on some of the best guidelines that we’ve come up with in designing our REST API.

REST API Design Guidelines

1. Keep your REST API resources coarse grained, not fine grained

Basically, you don’t know how your user is going to interact with your resources. In the case of Stormpath, resources would be accounts, groups, or directories. There are lots of different actions they might run on those resources and if they are adding in lots of arguments to methods they’ve written for a particular resource, it can be difficult to manage. So we recommend that, for a given resource in your REST API, you write a method that takes the resource itself as an argument, and the method contains all the functionality needed for said resource.

How else do you keep things coarse grained? You work with collection and instance resources. A collection resource is what it sounds like – basically a folder containing similar resources. An instance resource is a singular instance of its parent resource. This allows you to use HTTP behavior that affects an end point definition (an instance resource), but doesn’t actually create another url for each instance-behavior combination. So don’t add behavior to the actual end point definition.

2. Use POST to take advantage of partial updates in your REST API

Since REST APIs run on standard HTTP methods, you can use PUT or POST to either create or update resources. You might think of using PUT to create a resource and POST to update a resource, but you can actually use POST for both, and that’s recommended.

Why would you want to use POST to both create and update a resource?

Because with POST you don’t need to send over all fields for that data resource on every call you make, whereas with PUT, you do. This is important because if for every update you make you are also sending over fields that are not updating, then your data plan is consuming more than it needs to. Using POST instead of PUT can be beneficial if your REST API is metered as it limits the quantity of traffic. Furthermore, when you get into millions or hundreds of millions of requests per month, that impacts your REST API’s performance – so use POST to limit the traffic.

And why can’t you do the same with PUT?

Because per HTTP specification, PUT is idempotent, meaning it has to have all its properties included (or the result will not be the same). For example, if you first create an application without specifying a description, and then in a fourth call you send in the description, the state may have been different in between, therefore breaking the idempotency mandate.

3. Have REST API documents link to other documents based on the notion of a media type

A media type is a specification of a data format and a set of parsing rules associated with that specification. With your REST API, if you’re writing as a client, be sure to include your preferred data format you would like returned in the accept-header. Likewise, as the server, return back a content-type header that notes how the data is actually being returned. You can also add additional parsing rules to whatever data type you’re using. For example, you might have media type application/JSON+foo which tells the client not only is this JSON formatted data, but it’s also foo, which tells the client how to parse that data.

So make sure to send through accept headers specifying what media type you want (if on the client side), send through content-type headers telling the client what data format you are returning (if on server side), and take advantage of customizing your own media types to make your rest API more flexible for your clients.

Conclusion

In this post we’ve covered the advantages of the RESTful API design approach, as well as the fundamentals for creating a developer-friendly REST API. This is merely a summary of Les’ points, and only the first 30 minutes at that, so be sure to check out the rest of the presentation.