Representational State Transfer (REST) is an architectural style that defines a set of constraints to be used

for creating web services. REST API is a way of accessing web services in a simple and flexible way without
having any processing.
REST technology is generally preferred to the more robust Simple Object Access Protocol (SOAP) technology
because REST uses less bandwidth, simple and flexible making it more suitable for internet usage. It’s used
to fetch or give some information from a web service. All communication done via REST API uses only HTTP
request.
A request is sent from client to server in the form of a web URL as HTTP GET or POST or PUT or DELETE
request. After that, a response comes back from the server in the form of a resource which can be anything
like HTML, XML, Image, or JSON. But now JSON is the most popular format being used in Web Services.
A REST API (also known as RESTful API) is an application programming interface (API or web API) that
conforms to the constraints of REST architectural style and allows for interaction with RESTful web services.
REST stands for representational state transfer and was created by computer scientist Roy Fielding.

What is REST?

Representational State Transfer (REST) is a software architecture that imposes conditions on how an API
should work. REST was initially created as a guideline to manage communication on a complex network like
the internet. You can use REST-based architecture to support high-performing and reliable communication at
scale. You can easily implement and modify it, bringing visibility and cross-platform portability to any API
system.

API developers can design APIs using several different architectures. APIs that follow the REST architectural
style are called REST APIs. Web services that implement REST architecture are called RESTful web services.
The term RESTful API generally refers to RESTful web APIs. However, you can use the terms REST API and
RESTful API interchangeably.

The following are some of the principles of the REST architectural style:

Uniform interface

The uniform interface is fundamental to the design of any RESTful webservice. It indicates that the server
transfers information in a standard format. The formatted resource is called a representation in REST. This
format can be different from the internal representation of the resource on the server application. For example,
the server can store data as text but send it in an HTML representation format.

Uniform interface imposes four architectural constraints:

1. Requests should identify resources. They do so by using a uniform resource identifier.

2. Clients have enough information in the resource representation to modify or delete the resource if they
want to. The server meets this condition by sending metadata that describes the resource further.
3. Clients receive information about how to process the representation further. The server achieves this
by sending self-descriptive messages that contain metadata about how the client can best use them.

Bimal K Barik
 4. Clients receive information about all other related resources they need to complete a task. The server
achieves this by sending hyperlinks in the representation so that clients can dynamically discover
more resources.
Statelessness

In REST architecture, statelessness refers to a communication method in which the server completes every
client request independently of all previous requests. Clients can request resources in any order, and every
request is stateless or isolated from other requests. This REST API design constraint implies that the server can
completely understand and fulfill the request every time.

Layered system

In a layered system architecture, the client can connect to other authorized intermediaries between the client
and server, and it will still receive responses from the server. Servers can also pass on requests to other servers.
You can design your RESTful web service to run on several servers with multiple layers such as security,
application, and business logic, working together to fulfill client requests. These layers remain invisible to the
client.

Cacheability

RESTful web services support caching, which is the process of storing some responses on the client or on an
intermediary to improve server response time. For example, suppose that you visit a website that has common
header and footer images on every page. Every time you visit a new website page, the server must resend the
same images. To avoid this, the client caches or stores these images after the first response and then uses the
images directly from the cache. RESTful web services control caching by using API responses that define
themselves as cacheable or noncacheable.

Code on demand

In REST architectural style, servers can temporarily extend or customize client functionality by transferring
software programming code to the client. For example, when you fill a registration form on any website, your
browser immediately highlights any mistakes you make, such as incorrect phone numbers. It can do this
because of the code sent by the server.

What's an API?
An API is a set of definitions and protocols for building and integrating application software. It’s sometimes
referred to as a contract between an information provider and an information user—establishing the content
required from the consumer (the call) and the content required by the producer (the response). For example,
the API design for a weather service could specify that the user supply a zip code and that the producer reply
with a 2-part answer, the first being the high temperature, and the second being the low.

In other words, if you want to interact with a computer or system to retrieve information or perform a function,
an API helps you communicate what you want to that system so it can understand and fulfill the request.

You can think of an API as a mediator between the users or clients and the resources or web services they want
to get. It’s also a way for an organization to share resources and information while maintaining security, control,
and authentication—determining who gets access to what.

Another advantage of an API is that you don’t have to know the specifics of caching—how your resource is
retrieved or where it comes from.

Bimal K Barik
How do APIs work?
APIs let your product or service communicate with other products and services without having to know how
they’re implemented. This can simplify app development, saving time and money. When you’re designing new
tools and products—or managing existing ones—APIs give you flexibility; simplify design, administration, and
use; and provide opportunities for innovation.

APIs are sometimes thought of as contracts, with documentation that represents an agreement between
parties: If party 1 sends a remote request structured a particular way, this is how party 2’s software will
respond.

Because APIs simplify how developers integrate new application components into an existing architecture,
they help business and IT teams collaborate. Business needs often change quickly in response to ever shifting
digital markets, where new competitors can change a whole industry with a new app. In order to stay
competitive, it's important to support the rapid development and deployment of innovative services. Cloud-
native application development is an identifiable way to increase development speed, and it relies on
connecting a microservices application architecture through APIs.

APIs are a simplified way to connect your own infrastructure through cloud-native app development, but they
also allow you to share your data with customers and other external users. Public APIs represent unique
business value because they can simplify and expand how you connect with your partners, as well as potentially
monetize your data (the Google Maps API is a popular example).

For example, imagine a book-distributing company. The book distributor could give its customers a cloud
app that lets bookstore clerks check book availability with the distributor. This app could be expensive to
develop, limited by platform, and require long development times and ongoing maintenance.

Alternatively, the book distributor could provide an API to check stock availability. There are several benefits
to this approach:

• Letting customers access data via an API helps them aggregate information about their inventory in a
single place.
• The book distributor can make changes to its internal systems without impacting customers, so long
as the behavior of the API doesn’t change.

Bimal K Barik
 • With a publicly available API, developers working for the book distributor, book sellers or third parties
could develop an app to help customers find the books they’re looking for. This could result in higher
sales or other business opportunities.

In short, APIs let you open up access to your resources while maintaining security and control. How you open
access and to whom is up to you. API security is all about good API management, which includes the use of
an API gateway. Connecting to APIs, and creating applications that consume the data or functionality exposed
by APIs, can be done with a distributed integration platform that connects everything—including legacy
systems, and the Internet of Things (IoT).

Innovating with APIs

Exposing your APIs to partners or the public can:

• Create new revenue channels or extend existing ones.

• Expand the reach of your brand.
• Facilitate open innovation or improved efficiency through external development and collaboration.

Sounds great, right? But how can APIs do all that?

Let’s return to the example of the book distributing company.

Suppose one of the company's partners develops an app that helps people find books on bookstore shelves.
This improved experience brings more shoppers to the bookstore—the distributor's customer—and extends
an existing revenue channel.

Maybe a third party uses a public API to develop an app that lets people buy books directly from the distributor,
instead of from a store. This opens a new revenue channel for the book distributor.

Sharing APIs―with select partners or the whole world―can have positive effects. Each partnership extends
your brand recognition beyond your company’s marketing efforts. Opening technology to everyone, as with a
public API, encourages developers to build an ecosystem of apps around your API. More people using your
technology means more people are likely to do business with you.

Making technology public can lead to novel and unexpected outcomes. These outcomes sometimes disrupt
entire industries. For our book distributing company, new Birms―a book borrowing service, for example―could
fundamentally change the way they do business. Partner and public APIs help you use the creative efforts of a
community larger than your team of internal developers. New ideas can come from anywhere, and companies
need to be aware of changes in their market and ready to act on them. APIs can help.

An extraordinarily brief history of APIs

APIs emerged in the early days of computing, well before the personal computer. At the time, an API was
typically used as a library for operating systems. The API was almost always local to the systems on which it
operated, although it sometimes passed messages between mainframes. After nearly 30 years, APIs broke out
of their local environments. By the early 2000s, they were becoming an important technology for the remote
integration of data.

Remote APIs
Remote APIs are designed to interact through a communications network. By remote, we mean that the
resources being manipulated by the API are somewhere outside the computer making the request. Because the
most widely used communications network is the internet, most APIs are designed based on web standards.
Not all remote APIs are web APIs, but it’s fair to assume that web APIs are remote.

Bimal K Barik
Web APIs typically use HTTP for request messages and provide a definition of the structure of response
messages. These response messages usually take the form of an XML or JSON file. Both XML and JSON are
preferred formats because they present data in a way that’s easy for other apps to manipulate.

SOAP vs. REST

As web APIs have spread, a protocol specification was developed to help standardize information exchange:
Simple Object Access Protocol, more casually known as SOAP. APIs designed with SOAP use XML for their
message format and receive requests through HTTP or SMTP. SOAP makes it easier for apps running in different
environments or written in different languages to share information.

Another specification is Representational State Transfer (REST). Web APIs that adhere to the REST
architectural constraints are called RESTful APIs. REST differs from SOAP in a fundamental way: SOAP is a
protocol, whereas REST is an architectural style. This means that there’s no official standard for RESTful web
APIs. As defined in Roy Fielding’s dissertation “Architectural Styles and the Design of Network-based Software
Architectures,” APIs are RESTful as long as they comply with the 6 guiding constraints of a RESTful system:

• Client-server architecture: REST architecture is composed of clients, servers, and resources, and it
handles requests through HTTP.
• Statelessness: No client content is stored on the server between requests. Information about the
session state is, instead, held with the client.
• Cacheability: Caching can eliminate the need for some client-server interactions.
• Layered system: Client-server interactions can be mediated by additional layers. These layers could
offer additional features like load balancing, shared caches, or security.
• Code on demand (optional): Servers can extend the functionality of a client by transferring
executable code.
• Uniform interface: This constraint is core to the design of RESTful APIs and includes 4 facets:
o Resource identification in requests: Resources are identified in requests and are separate
from the representations returned to the client.
o Resource manipulation through representations: Clients receive files that represent
resources. These representations must have enough information to allow modification or
deletion.
o Self-descriptive messages: Each message returned to a client contains enough information
to describe how the client should process the information.
o Hypermedia as the engine of application state: After accessing a resource, the REST client
should be able to discover through hyperlinks all other actions that are currently available.

These constraints may seem like a lot but they’re much simpler than a prescribed protocol. For this reason
RESTful APIs are becoming more prevalent than SOAP.

In recent years, the OpenAPI specification has emerged as a common standard for defining REST APIs. OpenAPI
establishes a language-agnostic way for developers to build REST API interfaces so that users can understand
them with minimal guesswork.

Another API standard to emerge is GraphQL, a query language and server-side runtime that’s an alternative to
REST. GraphQL prioritizes giving clients exactly the data they request and no more. As an alternative to REST,
GraphQL lets developers construct requests that pull data from multiple data sources in a single API call.

SOA vs. microservices architecture

The 2 architectural approaches that use remote APIs most are service-oriented architecture (SOA) and
microservices architecture. SOA, the oldest of the 2 approaches, began as an improvement to monolithic apps.
Whereas a single monolithic app does everything, some functions can be supplied by different apps that are
loosely coupled through an integration pattern, like an enterprise service bus (ESB).

Bimal K Barik
While SOA is, in most respects, simpler than a monolithic architecture, it carries a risk of cascading changes
throughout the environment if component interactions are not clearly understood. This additional complexity
reintroduces some of the problems SOA sought to remedy.

Microservices architectures are similar to SOA patterns in their use of specialized, loosely coupled services. But
they go even further in breaking down traditional architectures. The services within the microservices
architecture use a common messaging framework, like RESTful APIs. They use RESTful APIs to communicate
with each other without difficult data conversion transactions or additional integration layers. Using RESTful
APIs allows, and even encourages, faster delivery of new features and updates. Each service is discrete. One
service can be replaced, enhanced, or dropped without affecting any other service in the architecture. This
lightweight architecture helps optimize distributed or cloud resources and supports dynamic scalability for
individual services.

RESTful API Design and Architecture Constraints

RESTful API design was defined by Dr. Roy Fielding in his 2000 doctorate dissertation. In order to be a true

RESTful API, a web service must adhere to the following six REST architectural constraints:

• Use of a uniform interface (UI). Resources should be uniquely identifiable through a single URL,

and only by using the underlying methods of the network protocol, such as DELETE, PUT and GET

with HTTP, should it be possible to manipulate a resource.

• Client-server based. There should be a clear delineation between the client and server. UI and

request-gathering concerns are the client's domain. Data access, workload management and

security are the server's domain. This loose coupling of the client and server enables each to be

developed and enhanced independent of the other.

• Stateless operations. All client-server operations should be stateless, and any state management

that is required should take place on the client, not the server.

• RESTful resource caching. All resources should allow caching unless explicitly indicated that

caching is not possible.

• Layered system. REST allows for an architecture composed of multiple layers of servers.

• Code on demand. Most of the time, a server will send back static representations of resources in

the form of XML or JSON. However, when necessary, servers can send executable code to the client.

Common REST API challenges

Besides the design and architecture constraints, individuals will have to confront some challenges with REST

APIs. Some concepts which may be challenging can include:

Bimal K Barik
 • Endpoint consistency -- paths of endpoints should be consistent by following common web

standards, which may be difficult to manage.

• API versioning -- endpoint URLs shouldn't be invalidated when used internally or with other

applications.

• Long response times and too much data -- the amount of returned resources can increase in size

in time, adding to increased load and response times.

• Navigation paths and user input locations -- because REST uses URL paths for input parameters,

determining URL spaces can be challenging.

• Security -- which has a lot of aspects to keep an eye on, including the use of:

o HTTPS;

o blocking access from unknown IP addresses and domains;

o validating URLs;

o blocking unexpectedly large payloads;

o logging requests; and

o investigating failures.

• Authentication -- use common authentication methods such as HTTP basic authentication (which

allows for a base64-encoded username:password string), API keys, JSON Web Tokens and other

access tokens. OAuth 2.0, for example, is good for access control.

• Requests and data -- requests may have more data and metadata than needed or more requests

may be needed to obtain all the data. APIs can be adjusted for this.

• API testing -- can be a long process to set up and run. Each part of the process can be either long

or challenging. Testing can also be done in the command line with the utility Curl. Parts of the

testing process that may be challenging include:

o Initial setup

o Schema updates

o Test parameter combinations

Bimal K Barik
 o Sequence API calls

o Validate test parameters

o System integration

• Define error codes and messages.

o With error codes, it is more of a common practice to use standard HTTP error codes.

These are recognized by clients and developers more often.

o Error handling may not have a way to distinguish if a response is successful or not

besides parsing the body or checking for an error.

RESTful APIs process

The basic function of a RESTful API is the same as browsing the internet. The client contacts the server by using
the API when it requires a resource. API developers explain how the client should use the REST API in the server
application API documentation. These are the general steps for any REST API call:

1. The client sends a request to the server. The client follows the API documentation to format the request
in a way that the server understands.
2. The server authenticates the client and confirms that the client has the right to make that request.
3. The server receives the request and processes it internally.
4. The server returns a response to the client. The response contains information that tells the client
whether the request was successful. The response also includes any information that the client
requested.

The REST API request and response details vary slightly depending on how the API developers design the API.

RESTful API client container

RESTful APIs require requests to contain the following main components:

Unique resource identifier

The server identifies each resource with unique resource identifiers. For REST services, the server typically
performs resource identification by using a Uniform Resource Locator (URL). The URL specifies the path to the
resource. A URL is similar to the website address that you enter into your browser to visit any webpage. The
URL is also called the request endpoint and clearly specifies to the server what the client requires.

Method

Developers often implement RESTful APIs by using the Hypertext Transfer Protocol (HTTP). An HTTP method
tells the server what it needs to do to the resource. The following are four common HTTP methods:

GET

Bimal K Barik
Clients use GET to access resources that are located at the specified URL on the server. They can cache GET
requests and send parameters in the RESTful API request to instruct the server to filter data before sending.

POST

Clients use POST to send data to the server. They include the data representation with the request. Sending the
same POST request multiple times has the side effect of creating the same resource multiple times.

PUT

Clients use PUT to update existing resources on the server. Unlike POST, sending the same PUT request multiple
times in a RESTful web service gives the same result.

DELETE

Clients use the DELETE request to remove the resource. A DELETE request can change the server state.
However, if the user does not have appropriate authentication, the request fails.

HTTP headers

Request headers are the metadata exchanged between the client and server. For instance, the request header
indicates the format of the request and response, provides information about request status, and so on.

Data

REST API requests might include data for the POST, PUT, and other HTTP methods to work successfully.

Parameters

RESTful API requests can include parameters that give the server more details about what needs to be done.
The following are some different types of parameters:

• Path parameters that specify URL details.

• Query parameters that request more information about the resource.
• Cookie parameters that authenticate clients quickly.

RESTful API authentication methods

A RESTful web service must authenticate requests before it can send a response. Authentication is the process
of verifying an identity. For example, you can prove your identity by showing an ID card or driver's license.
Similarly, RESTful service clients must prove their identity to the server to establish trust.

RESTful API has four common authentication methods:

HTTP authentication

HTTP defines some authentication schemes that you can use directly when you are implementing REST API.
The following are two of these schemes:

Basic authentication

In basic authentication, the client sends the user name and password in the request header. It encodes them
with base64, which is an encoding technique that converts the pair into a set of 64 characters for safe
transmission.

Bimal K Barik
Bearer authentication

The term bearer authentication refers to the process of giving access control to the token bearer. The bearer
token is typically an encrypted string of characters that the server generates in response to a login request. The
client sends the token in the request headers to access resources.

API keys

API keys are another option for REST API authentication. In this approach, the server assigns a unique
generated value to a first-time client. Whenever the client tries to access resources, it uses the unique API key
to verify itself. API keys are less secure because the client has to transmit the key, which makes it vulnerable to
network theft.

OAuth

OAuth combines passwords and tokens for highly secure login access to any system. The server first requests
a password and then asks for an additional token to complete the authorization process. It can check the token
at any time and also over time with a specific scope and longevity.

RESTful API server response contain

REST principles require the server response to contain the following main components:

Status line

The status line contains a three-digit status code that communicates request success or failure. For instance,
2XX codes indicate success, but 4XX and 5XX codes indicate errors. 3XX codes indicate URL redirection.

The following are some common status codes:

• 200: Generic success response

• 201: POST method success response
• 400: Incorrect request that the server cannot process
• 404: Resource not found
Message body

The response body contains the resource representation. The server selects an appropriate representation
format based on what the request headers contain. Clients can request information in XML or JSON formats,
which define how the data is written in plain text. For example, if the client requests the name and age of a
person named John, the server returns a JSON representation as follows:

'{"name":"John", "age":30}'

Headers

The response also contains headers or metadata about the response. They give more context about the
response and include information such as the server, encoding, date, and content type.

Bimal K Barik