What is RESTful API and what’s not

If you are a web developer, you’ve probably got confused at least once about “What is REST API and what’s not”.

People use both ‘REST API’ and ‘RESTful API’ in discussions or blogs. But it seems to be that many of them refer the terms without a concrete concept, just meaning “an API whose endpoint use nouns and is called via correct HTTP methods for CRUD action”.

Actually I am one of them. Thus, I looked up the concept of REST.

TL;DR

• REST is a software architectural style composed of 6 constraints
• An API that follows every rule is called RESTful API
• There’s no difference between REST API and RESTful API
• RESTful API implementations:

- Client holds state and put it on HTTP header or query parameter
- Use cookie to store state
- Use database server to store state
- Set appropriate cache-control header
- Make sure no proxies or gateways store state
- Set content-type header
- Response JSON shall always deliver resource data
- Response JSON should contain links object including manipulation directive and URI for that

REST = architectural style

REST, an acronym of REpresentational State Transfer, is introduced in 2000 by Roy Fielding in his paper.

Put it simply, REST is a style.

It is a standard, a guid line for well designed application. Roy intended to share an image of well-designed web applications for better scalability, performance, visibility, and more.

And in that big picture he introduced 6 constrains and any interface or architecture that satisfies those constrains is called as RESTful.

Let’s have a look at key concepts and constrains.

Key concepts

There are several key concepts to understand REST. I recommend you to at least grasp the idea for resource and representation.

refer to Roy Fielding’s dissertation

resource

= any information that can be named

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.

representation

= a state of the target resource at that point

The state of the 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 the next desired state.

6 constrains of REST interface

Constrains are for improvement of performance and scalability and other benefits.

1. Client-server architecture
2. Statelessness
3. Cacheability
4. Uniform interface
5. Layered system
6. Code-on-demand (optional)

advantage/disadvantage

For further explanation why each constrain improves each aspect, I recommend to read original paper. It’s not long.

What’s confusing?

There are two common misunderstandings worth mentioning.

Note 1: REST != HTTP

Roy Fielding did not mention any preference or directive about transfer protocol, and thus REST does not require to use HTTP. Any interaction interface that satisfies 6 constrains is referred to as RESTful interface. That said, REST fits well to HTTP protocol because Roy also contributed to HTTP 1.1 and URI standards.

Note 2: REST API == RESTful API ?

There’s no difference between REST API and RESTful API. Roy and later contributors described ‘RESTful’ and not ‘REST API’. The term ‘REST API’ is popular just because it looks neat and simple without ‘-ful’. Don’t worry, they shall be the same.

RESTful API

A RESTful API is an API that meets all 6 constrains.

In this section, we’ll see how to follow 6 constrains.

1. Client-server architecture

Basically you don’t need to pay attention to this in a modern API.A client should know only resource URIs, and that’s all.

RESTful API | Client-server
- (nothing to do)

2. Statelessness

The server will not store anything about the latest HTTP request the client made.

This becomes an issue when application needs an authentication.

What happens if you store login state of users? If you store user session information in server memory, load balancing would lead user to fail loading data randomly. Servers cannot scale out.

Issue for storing state in server

To solve this problem, always return state information and make client send state on every request.

authorization header

Another situation you have to take care of this is ‘shopping cart’ functionality. Since you cannot store state in servers, you need to either return cart information back to client every time or store it in you data-storing server(database, cache). It’s OK to store resource state another data-server and fetch it from application server.

RESTful API | Statelessness
- Make client put HTTP header or query parameter
- Use cookie to store state
- Use database server to store state

3. Cacheability

Cache constraints require that the data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable.

This rule means you have to explicitly response if the representation(=data, like HTML or PNG) is cacheable.

RESTful API | Cacheability
- Set appropriate cache-control header

4. Uniform interface

Uniform interface constrains are one central feature or REST.

Actually, this consists of 4 sub-principles and derived an enhanced practices later on, I summarized in another article.

(4-A) identification of resources

Individual resources are identified in requests using URIs in RESTful Web services.

You know you should use noun for URI, but before dive into detail, see what is not-RESTful.

Here’s a RPC style API endpoint. Endpoint is singular throughout application functions and everything is specified in request body.

refer to youtube

In REST, individual resources are identified in requests. To do that, resource identification endpoints

• contains nouns of resources

(4-B) manipulation of resources through representations

Server responses must have enough information for client to modify or delete the resource. Simply this means your response JSON and headers fulfill enough resource details.

(4-C) self-descriptive messages

REST enables intermediate processing by constraining messages to be self-descriptive: interaction is stateless between requests, standard methods and media types are used to indicate semantics and exchange information, and responses explicitly indicate cacheability.

A self-descriptive API satisfies:

• Every request responses contains information of cacheability ( cache-control header)
• Enable client to understand data format ( content-type header)
• No intermediaries such as proxy and gateway has state
• Modifying resource representations should not depends on intermediaries but the request from client determines

(4-D) hypermedia as the engine of application state(HATEOAS)

This constrain requires server to tells client what they can do next, and display URIs of the resource to manipulate/list resource representation.

For example, the HATEOAS response would be like this:

refer to Wikipedia

To sum up uniform interface constrains, RESTful API needs to:

RESTful API | Uniform interface
- Make sure no proxies or gateways store state
- Set cache-control header
- Set content-type header
- Response JSON shall always deliver resource data
- Response JSON should contain links object including manipulation directive and URI for that

5. Layered System

Each layer providing services to the layer above it and using services of the layer below it.

Most of the programming frameworks and cloud architecture are structured as layered. Do little about this while creating RESTful API.

Note intermediaries in RET includes:

• Proxies (chosen by client)
• Gateways (chosen by server)
• Firewalls

and not includes low level devices such as routers.

RESTful API | Layered system
- (nothing to do)

6. Code-on-demand (optional)

In the code-on-demand style, a client sends a request to a remote server for the code representing that know-how, receives that code, and executes it locally.

Code-on-demand implementations, for instance, use javascript or applet. But we focus on JSON returning APIs, there’s nothing to do.

Keep in mind that code-on-demand scripts reduces visibility.

Like remote evaluation, the most significant limitation is the lack of visibility due to the server sending code instead of simple data. Lack of visibility leads to obvious deployment problems if the client cannot trust the servers.

RESTful API | Code-on-demand
- (nothing to do)

What’s confusing for the constrains?

Note 1: REST does not restrict to use nouns

One of the most argued topic is that whether we should use only nouns in URIs. When you search for best practices, you’ll find some say “use only nouns” and others say “you can use verbs for control actions”.

Let me mention that at least the original dissertation did not order us to use nouns for URI. You won’t even find the word ‘noun’ in his paper. It just requires to make sure server can understand which resources to manipulate without using singular endpoint.

In addition, Martin Fowler, who proposed 4 levels of REST API, did not limit using verbs in URIs.

Of course, “resource” cannot be verb from lexical point of view, and Roy might have thought of composing request with resource noun + HTTP verb, I don’t think you have to use only nouns in endpoints.

Square API

Roy states by uniform interface “the overall system architecture is simplified and the visibility of interactions is improved”.

Used at the last of endpoints, verbs can improve visibility of interactions without loosing simplicity. Why not?

Note 2: resource noun is decoupled from table name

Same as above, REST itself does not care how you manage your data.

If you have polymorphic data structure or some other abstract model, you can use nouns that does not exist in your database in your URIs.

Note 3: which HTTP verb to use is not specified

As REST API tutorial describes below, Roy Fielding did not restrict which HTTP verb to use. REST is not even for HTTP-protocol specific principle in the first place.

Roy Fielding has never mentioned any recommendation around which method to be used in which condition. All he emphasizes is that it should be uniform interface. If you decide HTTP POST will be used for updating a resource — rather than most people recommend HTTP PUT — it’s alright and application interface will be RESTful.

However, later around 2010, Richardson Maturity Model is proposed by Martin Fowler and there exists a requirement to use appropriate HTTP verb in REST Level 2.

Now it’s better to select proper verb according to your action to the resource.

Note 4: response data format can be anything

Same as the previous one, REST does not restrict data format of responses. Thus you can use XML or JSON or whatever you want.

Should it be good to strictly follow REST principles?

In my opinion, there is not much reasons to follow REST strictly. Even APIs supported by tech giants aren’t fully oblige to the rule. Some of the principles, HATEOAS for example, seem to be less practical so far in addition to be difficult to manage.

I totally agree to create API that follow the rule as much as possible.

Rather, what’s important is to understand the definition and to know which principle your API satisfies and which is not. This will reduce miscommunication among your team and reduce the possibility of making a wrong decision in the future around this.

References

• Wikipedia
• Roy Fielding’s dissertation
• REST API tutorial
• This video make it clear because it explains what’s before REST
• This video also explains well with other style of interacting architecture
• Richardson Maturity Model(2010, Martin Fowler)
• Stripe API