How to Design a RESTful API

In order to understand how to design a RESTful API, you need to understand the concepts
behind REST. The next section explains REST briefly.

What is REST?

Scalability and performance are two of the main concerns when developing hypermedia
systems. Roy Fielding introduced an architectural style for distributed hypermedia systems
that focus on minimizing latency while maximizing scalability. The introduced architecture
leverages a number of web standards such as HTTP. In this architecture, a client sends a
request to a server to retrieve a specific resource. Then, the server responds back with a
specific representation of the requested resource, which puts the client in a specific
state. In other words, the client transfers its state to a new one with each resource
request. Hence, Roy Fielding named his architecture as Representational State Transfer
(REST).

So, what is a resource?

A resource is an entity that can be requested from client applications. Usually,
resources are nouns such as “BookTitle” and “ActorName”. When I think about resources, I
try to model the system using object oriented principles. Then, the resources are
basically the classes and objects, which are never verbs.

Since REST is based on HTTP standards, it maps each resource to a URI. For example,

http://example.com/books/01-23-45-67-89/BookTitle

The server can send different representations of the same resource, depending on the
request. For example, the client can ask for XML or JSON representations among others. It
is always recommended that the resource representation can be validated against some sort
of schema

Note that URIs represent tree hierarchies, but it doesn’t have to be the case. For
example, to represent a book in a specific section in a particular library you could do,

http://example.com/libraries/LibraryName/sections/SectionName/books/BookName

So, what if you need to represent a resource that isn’t in a tree hierarchy. For example,
if you would like to represent a point in an image using X-Y coordinates. Lets assume that
X=20 and Y=30. It doesn’t make sense and it is definitely not intuitive if you design the
resource like this:

http://example.com/image/12345/point/20/30

But you could do,

http://example.com/image/12345/point/20,30

The book named “Restful Web Services” by Leonard Richardson and Sam Ruby is a wonderful
source to similar URI tips. I highly recommend going through this book before you get into
business.

Challenges designing resources

REST identifies a resource as a URI and the operations on this resource are HTTP methods.
Although there are a number of HTTP methods, GET, POST, PUT, and DELETE are the most
common ones. GET and DELETE don’t need explanation, but POST and PUT are sometimes tricky.
The confusion comes from the wording of the HTTP RFC for the methods. So, here is the
deal.

You can use PUT and POST to create/modify the resource. The difference is that you use
POST if the client doesn’t know the final URI for the resource and use PUT if the client
knows the final URI of the resource. Let me demonstrate with an example.

Example 1:
Lets assume that the resource design is as follows:

http://example.com/books/

To create and/or modify a book the client should use PUT on this URI.

Example 2:
Lets assume that the resource design is as follows:

http://example.com/books//

In this case, the client doesn’t know the URI because it doesn’t know the generated-id for
the book to be created. Therefore the server should provide another URI to be hit with a
POST request such as

http://example.com/books/

The server should return the final URI of the book in its response to the POST request
from the client application.

Steps to design RESTful API

1. Identify resources and URIs.
   • Resources should be nouns.
   • Try to make the URI intuitive and easy to guess.
   • If in doubt, map it to object oriented system.
   • If still in doubt, ask for help.
2. Identify resource representation formats.
   • A resource can have one or more representation such as (JSON, XML, …etc).
   • Always have a schema to validate your resource representation against.
3. Identify supported HTTP methods.
   • Don’t use an uncommon HTTP method that may not be supported by the client application.
   • Use PUT when the client knows the final resource URI and use POST otherwise.
   • Use GET to get a specific representation of the resource.
   • Use DELETE to get rid of the resource .
   • Try to make your implementation idempotent.
4. Identify resource returned status codes.
   • Always use the standard HTTP status codes.
   • Always provide a return message to provide more information about the returned status.

Happy coding Please, share your thoughts !!