9/14/24, 10:54 PM What is REST?

: REST API Tutorial

REST API Tutorial

What is REST?
REST is an acronym for REpresentational State Transfer and an architectural style
for distributed hypermedia systems. Roy Fielding first presented it in 2000 in his
famous dissertation. Since then it has become one of the most widely used
approaches for building web-based APIs (Application Programming Interfaces).
REST is not a protocol or a …

Written by: Lokesh Gupta

Last Updated: December 12, 2023

REST is an acronym for REpresentational State Transfer and an architectural style

for distributed hypermedia systems. Roy Fielding first presented it in 2000 in his
famous dissertation. Since then it has become one of the most widely used
approaches for building web-based APIs (Application Programming Interfaces).

REST is not a protocol or a standard, it is an architectural style. During the

development phase, API developers can implement REST in a variety of ways.

Like the other architectural styles, REST also has its guiding principles and constraints.
These principles must be satisfied if a service interface has to be referred to
as RESTful.

https://restfulapi.net 1/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

A Web API (or Web Service) conforming to the REST architectural

style is called a REST API (or RESTful API).

1. The Six Guiding Principles of REST

REST is based on some constraints and principles that promote simplicity, scalability,
and statelessness in the design. The six guiding principles or constraints of the
RESTful architecture are:

1.1. Uniform Interface

By applying the principle of generality to the components interface, we can simplify

the overall system architecture and improve the visibility of interactions. Multiple
architectural constraints help in obtaining a uniform interface and guiding the
behavior of components.

The following four constraints can achieve a uniform REST interface:

https://restfulapi.net 2/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

Identification of resources – The interface must uniquely identify each

resource involved in the interaction between the client and the server.

Manipulation of resources through representations – The resources should

have uniform representations in the server response. API consumers should
use these representations to modify the resource state in the server.

Self-descriptive messages – Each resource representation should carry

enough information to describe how to process the message. It should also
provide information of the additional actions that the client can perform on
the resource.

Hypermedia as the engine of application state – The client should have only
the initial URI of the application. The client application should dynamically
drive all other resources and interactions with the use of hyperlinks.

In simpler words, REST defines a consistent and uniform interface for interactions
between clients and servers. For example, the HTTP-based REST APIs make use of the
standard HTTP methods (GET, POST, PUT, DELETE, etc.) and the URIs (Uniform
Resource Identifiers) to identify resources.

1.2. Client-Server

The client-server design pattern enforces the separation of concerns, which helps the
client and the server components evolve independently.

By separating the user interface concerns (client) from the data storage concerns
(server), we improve the portability of the user interface across multiple platforms
and improve scalability by simplifying the server components.

While the client and the server evolve, we have to make sure that the
interface/contract between the client and the server does not break.

1.3. Stateless

https://restfulapi.net 3/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

Statelessness mandates that each request from the client to the server must contain
all of the information necessary to understand and complete the request.

The server cannot take advantage of any previously stored context information on
the server.

For this reason, the client application must entirely keep the session state.

1.4. Cacheable

The cacheable constraint requires that a response should implicitly or explicitly label
itself as cacheable or non-cacheable.

If the response is cacheable, the client application gets the right to reuse the
response data later for equivalent requests and a specified period.

1.5. Layered System

The layered system style allows an architecture to be composed of hierarchical layers

by constraining component behavior. In a layered system, each component cannot
see beyond the immediate layer they are interacting with.

A layman’s example of a layered system is the MVC pattern. The MVC pattern allows
for a clear separation of concerns, making it easier to develop, maintain, and scale
the application.

1.6. Code on Demand (Optional)

REST also allows client functionality to extend by downloading and executing code in
the form of applets or scripts.

The downloaded code simplifies clients by reducing the number of features required
to be pre-implemented. Servers can provide part of features delivered to the client in
the form of code, and the client only needs to execute the code.

https://restfulapi.net 4/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

2. What is a Resource?
The key abstraction of information in REST is a resource. Any information that we
can name can be a resource. For example, a REST resource can be a document or
image, a temporal service, a collection of other resources, or a non-virtual object
(e.g., a person).

The state of the resource, at any particular time, is known as the resource
representation. The resource representations consist of:

the data

the metadata describing the data

and the hypermedia links that can help the clients transition to the next
desired state.

A REST API consists of an assembly of interlinked resources. This

set of resources is known as the REST API’s resource model.

2.1. Resource Identifiers

REST uses resource identifiers to identify each resource involved in the interactions
between the client and the server components.

2.2. Hypermedia

The data format of a representation is known as a media type. The media type
identifies a specification that defines how a representation is to be processed.

A RESTful API looks like hypertext. Every addressable unit of information carries an
address, either explicitly (e.g., link and id attributes) or implicitly (e.g., derived from
the media type definition and representation structure).

https://restfulapi.net 5/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

Hypertext (or hypermedia) means the simultaneous presentation

of information and controls such that the information becomes
the affordance through which the user (or automaton) obtains
choices and selects actions.

Remember that hypertext does not need to be HTML (or XML or

JSON) on a browser. Machines can follow links when they
understand the data format and relationship types.

— Roy Fielding

2.3. Self-Descriptive

Further, resource representations shall be self-descriptive: the client does not need
to know if a resource is an employee or a device. It should act based on the media
type associated with the resource.

So in practice, we will create lots of custom media types – usually one media type
associated with one resource.

Every media type defines a default processing model. For example, HTML defines a
rendering process for hypertext and the browser behavior around each element.

Media Types have no relation to the resource methods

GET/PUT/POST/DELETE/… other than the fact that some media
type elements will define a process model that goes like “anchor
elements with an href attribute create a hypertext link that, when
selected, invokes a retrieval request (GET) on the URI
corresponding to the CDATA-encoded href attribute.”

2.4. Example
https://restfulapi.net 6/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

Consider the following REST resource that represents a blog post with links to related
resources in an HTTP-based REST API. This has the necessary information about the
blog post, as well as the hypermedia links to the related resources such as author and
comments. Clients can follow these links to discover additional information or
perform actions.

{
"id": 123,
"title": "What is REST",
"content": "REST is an architectural style for building web services
"published_at": "2023-11-04T14:30:00Z",
"author": {
"id": 456,
"name": "John Doe",
"profile_url": "https://example.com/authors/456"
},
"comments": {
"count": 5,
"comments_url": "https://example.com/posts/123/comments"
},
"self": {
"link": "https://example.com/posts/123"
}
}

3. Resource Methods
Another important thing associated with REST is resource methods. These resource
methods are used to perform the desired transition between two states of any
resource.

A large number of people wrongly relate resource methods to HTTP methods (i.e.,
GET/PUT/POST/DELETE). Roy Fielding has never mentioned any recommendation
around which method to use in which condition. All he emphasizes is that it should
be a uniform interface.
https://restfulapi.net 7/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

For example, if we decide that the application APIs will use HTTP POST for updating a
resource – rather than most people recommend HTTP PUT – it’s all right. Still, the
application interface will be RESTful.

Ideally, everything needed to transition the resource state shall be part of the
resource representation – including all the supported methods and what form they
will leave the representation.

We should enter a REST API with no prior knowledge beyond the

initial URI (a bookmark) and a set of standardized media types
appropriate for the intended audience (i.e., expected to be
understood by any client that might use the API).

From that point on, all application state transitions must be driven
by the client selection of server-provided choices present in the
received representations or implied by the user’s manipulation of
those representations.

The transitions may be determined (or limited by) the client’s

knowledge of media types and resource communication
mechanisms, both of which may be improved on the fly
(e.g., code-on-demand). [Failure here implies that out-of-band
information is driving interaction instead of hypertext.]

4. REST and HTTP are Not the Same

Many people prefer to compare HTTP with REST. REST and HTTP are not the same.

REST != HTTP

https://restfulapi.net 8/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

Though REST also intends to make the web (internet) more streamlined and standard,
Roy Fielding advocates using REST principles more strictly. And that’s where people
try to start comparing REST with the web.

Roy Fielding, in his dissertation, has nowhere mentioned any implementation

direction – including any protocol preference or even HTTP. Till the time, we are
honoring the six guiding principles of REST, which we can call our interface – RESTful.

5. Summary
In simple words, in the REST architectural style, data and functionality are considered
resources and are accessed using Uniform Resource Identifiers (URIs).

The resources are acted upon by using a set of simple, well-defined operations. Also,
the resources have to be decoupled from their representation so that clients can
access the content in various formats, such as HTML, XML, plain text, PDF, JPEG,
JSON, and others.

The clients and servers exchange representations of resources by using a

standardized interface and protocol. Typically HTTP is the most used protocol, but
REST does not mandate it.

Metadata about the resource is made available and used to control caching, detect
transmission errors, negotiate the appropriate representation format, and perform
authentication or access control.

And most importantly, every interaction with the server must be stateless.

All these principles help RESTful applications to be simple, lightweight, and fast.

Happy Learning !!

References:

REST APIs must be hypertext-driven

https://restfulapi.net 9/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

REST Arch Style

Comments

 Subscribe 

Join the discussion

{} [+]

26 COMMENTS   Most Voted 

Ravan
 4 years ago

Can we say “If an API is following 6 guiding Principles of REST then it’s a RESTful API”?

28 Reply

Lokesh Gupta
 Reply to Ravan  4 years ago

Yes

23 Reply

Jay
 Reply to Lokesh Gupta  3 years ago

The original sentence, “Till the time, you are honoring the 6 guiding principles of
REST, you can call your interface RESTful” threw me. I interpret it to mean “Unless
you honor the six guiding principles of REST, you cannot call your interface
RESTful.” Rowan’s text is equally clear.

Why not change the webpage text to make it clearer?

https://restfulapi.net 10/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

3 Reply

Lokesh Gupta
 Reply to Jay  3 years ago

Unfortunately, there is no defined word for APIs that partially follow these
principles.

0 Reply

Person
 Reply to Ravan  4 years ago

Or a RESTed API.

And if it’s migrating from being an API that isn’t RESTed to one that is, you can say it’s
under arREST 😉

12 Reply

Dave Young
 4 years ago

Regarding the 6th guiding principle – coding on demand, does this include single page
application in which code is downloaded from a server to the UI when invoked?

18 Reply

Lokesh Gupta
 Reply to Dave Young  4 years ago

REST principles are not affected by SPA design.

6 Reply

Lokesh Gupta
 4 years ago

I will suggest using all lowercase seperated with hyphens.

15 Reply

Deepak
 Reply to Lokesh Gupta  3 months ago

https://restfulapi.net 11/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

instead of hyphen I suggest underscore

-1 Reply

Lokesh Gupta
 Reply to Deepak  2 months ago

Please think twice. Even Google suggests hyphens in the URLs.

3 Reply

Alexander
 4 years ago

“Another thing which will help you while building RESTful APIs is that query based API results
should be represented by a list of links with summary information, not by arrays of original
resource representations because the query is not a substitute for identification of resources.”

I struggle to comprehend this without an example. Let us say, our API is supposed to retrieve
data, such as employee data from database server in JSON format to be consumed by client
app. What is “a list of links with summary information” that we can expect as the result of the
API.
Currently I am using PHP + Laravel. Maybe someone can explain or give an example of the
above statement, preferably using Laravel routing statement.

7 Reply

Lokesh Gupta
 Reply to Alexander  4 years ago

The article suggests using URIs and respective response structures as below.

If we will provide full device information in search query results, the client may start
using these URIs to get and utilize individual device information – Which is wrong.

For example, '/devices?id=1' should never be alternative to '/devices/1'.

<devices size="3">
<device id="1">
<link rel="self" href="/devices/1"/>
<name>apple-srx_201</name>
<serialNumber>1111</serialNumber>
<connectionStatus>up</connectionStatus>

https://restfulapi.net 12/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

</device>
<device id="2">
<link rel="self" href="/devices/2"/>
<name>apple-srx_202</name>
<serialNumber>2222</serialNumber>
<connectionStatus>down</connectionStatus>
</device>
<device id="3">
<link rel="self" href="/devices/3"/>
<name>apple-srx_203</name>
<serialNumber>3333</serialNumber>
<connectionStatus>up</connectionStatus>
</device>
</devices>

<device id="1">
<link rel="self" href="/devices/1"/>
<deviceFamily>apple-es</deviceFamily>
<OSVersion>10.3R2.11</OSVersion>
<platform>SRX100B</platform>
<serialNumber>32423457</serialNumber>
<connectionStatus>up</connectionStatus>
<ipAddr>192.168.21.9</ipAddr>
<name>apple-srx_200</name>
<status>active</status>
</device>

14 Reply

Alexander
 Reply to Lokesh Gupta  4 years ago

Thanks for your reply. I have read other articles by you, especially :
https://restfulapi.net/rest-api-design-tutorial-with-example/.
When you discuss two resource types there, i.e collection and single, and explain
why we should provide different responses to these resource types , I understand
your suggestion above. Hence I also get what HATEOAS means.
Thanks again.

https://restfulapi.net 13/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

7 Reply

Jason Packer
 4 years ago

My previous firm used camel case notation.

3 Reply

Chandrajeet Choudhary
 Reply to Jason Packer  4 years ago

I suggest never use camel case notation. You should use all lowercase separated with
hyphens. It helps in SEO.

1 Reply

Luis
 Reply to Chandrajeet Choudhary  4 years ago

But is it important the SEO in an API?

Maybe using lowercase seperated with hyphens is better to read.

5 Reply

Tiamo
 Reply to Luis  3 years ago

Not at all. The API url’s should never get any eyes from the end-user, so
they aren’t important for SEO.

0 Reply

Andrea
 1 year ago

Those are http verbs, As stated in the article HTTP != REST

2 Reply

Ramesh Sunkara
 4 months ago

https://github.com/rameshsunkara/go-rest-api-example

https://restfulapi.net 14/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

An enterprise ready owasp compliant open API 3 specification and implementation.

1 Reply

Anto
 4 years ago

> So in practice, you will end up creating lots of custom media-types – normally one media-
type associated with one resource.

Put in this way, IMHO, I think the sentence is misleading. Reading the phrase what I understand
is that for each resource I MUST create a custom media type, for example
application/vnd.book+json, application/vnd.author+json and application/vnd.user+json if my
application handles book, author and user resources. Albeit this is not forbidden by the REST
principles I think that a more appropriate sentence would be:

> So in practice, you CAN end up creating lots of custom media-types – POTENTIALLY one
media-type associated with one resource.

0 Reply

Snehal Masne
 6 years ago

What needs to be done to make the REST architectural style clear on the notion that hypertext
is a constraint? In other words, if the engine of application state (and hence the API) is not
being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period. Is there
some broken manual somewhere that needs to be fixed?

-1 Reply

Arnaud
 Reply to Snehal Masne  7 months ago

Hypermedia. Not simply hypertext.

-1 Reply

Brad Andrew Johnson

 1 year ago

This model of REST may be revelavent in your world, but I read this and can’t think of a real
world application.

https://restfulapi.net 15/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

-4 Reply

Lokesh Gupta
 Reply to Brad Andrew Johnson  1 year ago

Yes, following all principles is not possible all the time. The same thing happens with
other texts such as TDD or agile. Following these in their raw form is not possible in
real world.

4 Reply

paulsofts
 Reply to Lokesh Gupta  8 months ago

Please correct me if I’m wrong.

A simple Spring Boot application that demonstrates CRUD operations follows all
the principles:
1) Stateless.
2) Resource identification is done through URIs, and a uniform interface is
maintained for CRUD operations.
3) Caching can be added at the API Gateway for performance improvement.
4) The application follows a client-server architecture.
5) The architecture is layered, with a clear separation between the presentation
layer, business layer, and persistence layer.

0 Reply

Lokesh Gupta
 Reply to paulsofts  7 months ago

It is never about any framework. Spring boot, Jersey or even PHP, its not
about underlying technology. It is mostly about what exposed outside.
In your example, you missed Hypermedia, and it is also possible in Spring
Boot.

1 Reply

Learn REST

What is REST?

https://restfulapi.net 16/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

REST Constraints

Naming REST Resources

Guides

Caching

Compression

Content Negotiation

HATEOAS

Idempotence

Security Essentials

Versioning

Statelessness

Tech – How To

Design REST APIs

Design API for Long-Running Tasks

REST APIs with JAX-RS

FAQs

PUT vs POST

N+1 Problem

‘q’ Parameter

Resources

https://restfulapi.net 17/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

What is an API?

SOAP vs REST

HTTP Methods

Richardson Maturity Model

HTTP Response Codes

200 (OK)

201 (Created)

202 (Accepted)

204 (No Content)

301 (Moved Permanently)

About Lokesh Gupta

A fun-loving family man, passionate about computers and problem-solving, with over 15
years of experience in Java and related technologies. An avid Sci-Fi movie enthusiast and
a fan of Christopher Nolan and Quentin Tarantino.

Follow on Twitter

AD

https://restfulapi.net 18/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

AD

AD

https://restfulapi.net 19/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

AD

https://restfulapi.net 20/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

AD

References

The dissertation by Roy Thomas Fielding

Uniform Resource Identifier (URI, URL, URN) [RFC 3986]

Internet MediaTypes

Web Application Description Language (WADL)

https://restfulapi.net 21/22
9/14/24, 10:54 PM What is REST?: REST API Tutorial

Meta Links

About

Contact Us

Privacy Policy

Blogs

How To Do In Java

Copyright © 2023 • Sitemap

https://restfulapi.net 22/22