uniform interface

• What Is REST?

The REST architectural style describes six constraints. These constraints, applied to the architecture, were originally communicated by Roy Fielding in his doctoral dissertation (see https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm ) and defines the basis of RESTful-style.

The six constraints are: (click the constraint to read more)

The uniform interface constraint defines the interface between clients and servers. It simplifies and decouples the architecture, which enables each part to evolve independently. The four guiding principles of the uniform interface are:

Resource-Based

Individual resources are identified in requests using URIs as resource identifiers. The resources themselves are conceptually separate from the representations that are returned to the client. For example, the server does not send its database, but rather, some HTML, XML or JSON that represents some database records expressed, for instance, in Finnish and encoded in UTF-8, depending on the details of the request and the server implementation.

Manipulation of Resources Through Representations

When a client holds a representation of a resource, including any metadata attached, it has enough information to modify or delete the resource on the server, provided it has permission to do so.

Self-descriptive Messages

Each message includes enough information to describe how to process the message. For example, which parser to invoke may be specified by an Internet media type (previously known as a MIME type). Responses also explicitly indicate their cache-ability.

Hypermedia as the Engine of Application State (HATEOAS)

Clients deliver state via body contents, query-string parameters, request headers and the requested URI (the resource name). Services deliver state to clients via body content, response codes, and response headers. This is technically referred-to as hypermedia (or hyperlinks within hypertext).

Aside from the description above, HATEOS also means that, where necessary, links are contained in the returned body (or headers) to supply the URI for retrieval of the object itself or related objects. We'll talk about this in more detail later.

The uniform interface that any REST services must provide is fundamental to its design.

As REST is an acronym for REpresentational State Transfer, statelessness is key. Essentially, what this means is that the necessary state to handle the request is contained within the request itself, whether as part of the URI, query-string parameters, body, or headers. The URI uniquely identifies the resource and the body contains the state (or state change) of that resource. Then after the server does it's processing, the appropriate state, or the piece(s) of state that matter, are communicated back to the client via headers, status and response body.

Most of us who have been in the industry for a while are accustomed to programming within a container which provides us with the concept of “session” which maintains state across multiple HTTP requests. In REST, the client must include all information for the server to fulfill the request, resending state as necessary if that state must span multiple requests. Statelessness enables greater scalability since the server does not have to maintain, update or communicate that session state. Additionally, load balancers don't have to worry about session affinity for stateless systems.

So what's the difference between state and a resource? State, or application state, is that which the server cares about to fulfill a request—data necessary for the current session or request. A resource, or resource state, is the data that defines the resource representation—the data stored in the database, for instance. Consider application state to be data that could vary by client, and per request. Resource state, on the other hand, is constant across every client who requests it.

Ever had back-button issues with a web application where it went AWOL at a certain point because it expected you to do things in a certain order? That's because it violated the statelessness principle. There are cases that don't honor the statelessness principle, such as three-legged OAuth, API call rate limiting, etc. However, make every effort to ensure that application state doesn't span multiple requests of your service(s).

As on the World Wide Web, clients can cache responses. Responses must therefore, implicitly or explicitly, define themselves as cacheable, or not, to prevent clients reusing stale or inappropriate data in response to further requests. Well-managed caching partially or completely eliminates some client–server interactions, further improving scalability and performance.

The uniform interface separates clients from servers. This separation of concerns means that, for example, clients are not concerned with data storage, which remains internal to each server, so that the portability of client code is improved. Servers are not concerned with the user interface or user state, so that servers can be simpler and more scalable. Servers and clients may also be replaced and developed independently, as long as the interface is not altered.

A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way. Intermediary servers may improve system scalability by enabling load-balancing and by providing shared caches. Layers may also enforce security policies.

Servers are able to temporarily extend or customize the functionality of a client by transferring logic to it that it can execute. Examples of this may include compiled components such as Java applets and client-side scripts such as JavaScript.

Complying with these constraints, and thus conforming to the REST architectural style, will enable any kind of distributed hypermedia system to have desirable emergent properties, such as performance, scalability, simplicity, modifiability, visibility, portability and reliability.

NOTE: The only optional constraint of REST architecture is code on demand. If a service violates any other constraint, it cannot strictly be referred to as RESTful.

• REST Quick Tips
• HTTP Methods
• Resource Naming
• Idempotence
• HTTP Status Codes

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  RE presentational  S tate  T ransfer 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 .

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:

• 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

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.

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).

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

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.

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 .

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

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.

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
• REST Arch Style

About Lokesh Gupta

• DSA with JS - Self Paced
• JS Tutorial
• JS Exercise
• JS Interview Questions
• JS Operator
• JS Projects
• JS Examples
• JS Free JS Course
• JS A to Z Guide
• JS Formatter

REST API Architectural Constraints

• REST API Introduction
• REST API in Hyperledger
• Comparison between GraphQL & RESTful Architecture
• Best Coding Practices For Rest API Design
• What are Request Parameters in Postman ?
• FastAPI - Rest Architecture
• Service-Oriented Architecture
• Best Practices For Naming API Endpoints in a RESTful Architecture
• FastAPI Architecture
• Constrained Application Protocol (CoAP)
• Software Engineering | Architectural Design
• System Design of Uber App | Uber System Architecture
• Testing REST API with Postman and curl
• What is API Integration?
• SQL | Constraints
• Create a CRUD API With PostgREST
• GraphQL Federation with Microservices Architecture
• Postman vs. Rest Assured for API Testing
• GraphQL Architecture

REST stands for REpresentational State Transfer and API stands for Application Program Interface. REST is a software architectural style that defines the set of rules to be used for creating web services. Web services which follow the REST architectural style are known as RESTful web services. It allows requesting systems to access and manipulate web resources by using a uniform and predefined set of rules. Interaction in REST based systems happen through Internet’s Hypertext Transfer Protocol (HTTP). 

A Restful system consists of a:

• client who requests for the resources.
• server who has the resources.

It is important to create REST API according to industry standards which results in ease of development and increase client adoption. 

Architectural Constraints of RESTful API: There are six architectural constraints which makes any web service are listed below:

• Uniform Interface
• Client-Server
• Layered System
• Code on Demand

The only optional constraint of REST architecture is code on demand. If a service violates any other constraint, it cannot strictly be referred to as RESTful. 

Uniform Interface: It is a key constraint that differentiate between a REST API and Non-REST API. It suggests that there should be an uniform way of interacting with a given server irrespective of device or type of application (website, mobile app). 

There are four guidelines principle of Uniform Interface are:

• Resource-Based: Individual resources are identified in requests. For example: API/users.
• Manipulation of Resources Through Representations: Client has representation of resource and it contains enough information to modify or delete the resource on the server, provided it has permission to do so. Example: Usually user get a user id when user request for a list of users and then use that id to delete or modify that particular user.
• Self-descriptive Messages: Each message includes enough information to describe how to process the message so that server can easily analyses the request.
• Hypermedia as the Engine of Application State (HATEOAS): It need to include links for each response so that client can discover other resources easily.

Stateless: It means that the necessary state to handle the request is contained within the request itself and server would not store anything related to the session. In REST, the client must include all information for the server to fulfill the request whether as a part of query params, headers or URI. Statelessness enables greater availability since the server does not have to maintain, update or communicate that session state. There is a drawback when the client need to send too much data to the server so it reduces the scope of network optimization and requires more bandwidth.

Cacheable: Every response should include whether the response is cacheable or not and for how much duration responses can be cached at the client side. Client will return the data from its cache for any subsequent request and there would be no need to send the request again to the server. A well-managed caching partially or completely eliminates some client–server interactions, further improving availability and performance. But sometime there are chances that user may receive stale data. 

Client-Server: REST application should have a client-server architecture. A Client is someone who is requesting resources and are not concerned with data storage, which remains internal to each server, and server is someone who holds the resources and are not concerned with the user interface or user state. They can evolve independently. Client doesn’t need to know anything about business logic and server doesn’t need to know anything about frontend UI. 

Layered system: An application architecture needs to be composed of multiple layers. Each layer doesn’t know any thing about any layer other than that of immediate layer and there can be lot of intermediate servers between client and the end server. Intermediary servers may improve system availability by enabling load-balancing and by providing shared caches. 

Code on demand: It is an optional feature. According to this, servers can also provide executable code to the client. The examples of code on demand may include the compiled components such as Java Servlets and Server-Side Scripts such as JavaScript. 

Rules of REST API: There are certain rules which should be kept in mind while creating REST API endpoints.

• REST is based on the resource or noun instead of action or verb based. It means that a URI of a REST API should always end with a noun. Example: /api/users is a good example, but /api?type=users is a bad example of creating a REST API.
• HTTP verbs are used to identify the action. Some of the HTTP verbs are – GET, PUT, POST, DELETE, GET, PATCH.
• A web application should be organized into resources like users and then uses HTTP verbs like – GET, PUT, POST, DELETE to modify those resources. And as a developer it should be clear that what needs to be done just by looking at the endpoint and HTTP method used.
• Always use plurals in URL to keep an API URI consistent throughout the application.
• Send a proper HTTP code to indicate a success or error status.

Note : You can easily use GET and POST but in order to use PUT and DELETE you will need to install method override. You can do this by following below code :

This simply require this package in your code by writing :

Now you can easily use PUT and DELETE routes :

HTTP verbs: Some of the common HTTP methods/verbs are described below:

• GET: Retrieves one or more resources identified by the request URI and it can cache the information receive.
• POST: Create a resource from the submission of a request and response is not cacheable in this case. This method is unsafe if no security is applied to the endpoint as it would allow anyone to create a random resource by submission.
• PUT: Update an existing resource on the server specified by the request URI.
• DELETE: Delete an existing resource on the server specified by the request URI. It always return an appropriate HTTP status for every request.
• GET, PUT, DELETE methods are also known as Idempotent methods. Applying an operation once or applying it multiple times has the same effect. Example: Delete any resource from the server and it succeeds with 200 OK and then try again to delete that resource than it will display an error message 410 GONE.

Please Login to comment...

Similar reads.

• Web Technologies

Improve your Coding Skills with Practice

What kind of Experience do you want to share?

Hands-On RESTful API Design Patterns and Best Practices by Harihara Subramanian, Pethuru Raj

Get full access to Hands-On RESTful API Design Patterns and Best Practices and 60K+ other titles, with a free 10-day trial of O'Reilly.

There are also live events, courses curated by job role, and more.

Understanding the uniform interface

As we mentioned earlier in the uniform interface section as part of ROA, REST-based services can use the HTTP interface, such as GET , POST , PUT , DELETE , and so on, to maintain uniformity across the web. The intention of a uniform interface is to retain some common vocabulary across the internet. For example, GET does mean to get (read) something from the server. The services can independently evolve as their interfaces simplify and decouple the architecture, and the uniform interface brings a uniform vocabulary to those resources as well. The following diagram depicts the combination of HTTP Methods and the Resource Names for Uniform Interfaces :

There are four guiding principles suggested by Fielding that ...

Get Hands-On RESTful API Design Patterns and Best Practices now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Don’t leave empty-handed

Get Mark Richards’s Software Architecture Patterns ebook to better understand how to design components—and how they should interact.

It’s yours, free.

Check it out now on O’Reilly

Dive in for free with a 10-day trial of the O’Reilly learning platform—then explore all the other resources our members count on to build skills and solve problems every day.

A REST API (also called a RESTful API or RESTful web API) is an application programming interface (API) that conforms to the design principles of the representational state transfer (REST) architectural style. REST APIs provide a flexible, lightweight way to integrate applications and to connect components in microservices architectures.  

First, defined in 2000 by computer scientist Dr. Roy Fielding in his doctoral dissertation, REST provides a relatively high level of flexibility, scalability and efficiency for developers. For these reasons, REST APIs have emerged as a common method for connecting components and applications in a  microservices  architecture.

This ebook aims to debunk myths surrounding observability and showcase its role in the digital world.

Read a guide to intelligent automation

All API requests for the same resource should look the same, no matter where the request comes from. The REST API should ensure that the same piece of data, such as the name or email address of a user, belongs to only one uniform resource identifier (URI). Resources shouldn’t be too large but should contain every piece of information that the client might need.

In REST API design, client and server applications must be completely independent of each other. The only information that the client application should know is the URI of the requested resource; it can't interact with the server application in any other ways. Similarly, a server application shouldn't modify the client application other than passing it to the requested data via HTTP.

REST APIs are stateless, meaning that each request needs to include all the information necessary for processing it. In other words, REST APIs do not require any server-side sessions. Server applications aren’t allowed to store any data related to a client request.

When possible, resources should be cacheable on the client or server side. Server responses also need to contain information about whether caching is allowed for the delivered resource. The goal is to improve performance on the client side, while increasing scalability on the server side.

In REST APIs, the calls and responses go through different layers. As a rule of thumb, don’t assume that the client, and server applications connect directly to each other. There may be a number of different intermediaries in the communication loop. REST APIs need to be designed so that neither the client nor the server can tell whether it communicates with the end application or an intermediary.

REST APIs usually send static resources, but in certain cases, responses can also contain executable code (such as Java applets). In these cases, the code should only run on-demand.

REST APIs communicate through HTTP requests to perform standard database functions like creating, reading, updating and deleting records (also known as CRUD) within a resource.

For example, a REST API would use a GET request to retrieve a record. A POST request creates a new record. A PUT request updates a record, and a DELETE request deletes one. All HTTP methods can be used in API calls. A well-designed REST API is similar to a website running in a web browser with built-in HTTP functionality.

The state of a resource at any particular instant, or timestamp, is known as the resource representation. This information can be delivered to a client in virtually any format including JavaScript Object Notation (JSON), HTML, XLT, Python, PHP or plain text. JSON is popular because it’s readable by both humans and machines—and it is programming language-agnostic.

Request headers and parameters are also important in REST API calls because they include important identifier information such as metadata, authorizations, uniform resource identifiers (URIs), caching, cookies and more. Request headers and response headers, along with conventional HTTP status codes, are used within well-designed REST APIs.

Although flexibility is a big advantage of REST API design, that same flexibility makes it easy to design an API that’s broken or performs poorly. For this reason, professional developers share best practices in REST API specifications.

The OpenAPI Specification (OAS) establishes an interface for describing an API in a way that allows any developer or application to discover it and fully understand its parameters and capabilities. This information includes available endpoints, allowed operations on each endpoint, operation parameters, authentication methods and more. The latest version, OAS3 , includes with hands-on tools, such as the OpenAPI Generator, for generating API clients and server stubs in different programming languages.

Securing a REST API also starts with industry best practices. Use hashing algorithms for password security and HTTPS for secure data transmission. An authorization framework like OAuth 2.0  can help limit the privileges of third-party applications.

Using a timestamp in the HTTP header, an API can also reject any request that arrives after a certain time period. Parameter validation and JSON Web Tokens are other ways to ensure that only authorized clients can access the API.

Manage your API lifecycle across multiple clouds, boost socialization and optimize monetization efforts across your entire business ecosystem with the secure API management of IBM API Connect®.

Connect, automate and unlock business potential with Integration solutions.

Connect applications, data, business processes, and services, whether they are hosted on-premises, in a private cloud, or within a public cloud environment.

Learn how application programming interfaces, or APIs, simplify software development and innovation by enabling applications to exchange data and functionality easily and securely.

Learn about API management and how a unified API management platform can help your organization scale.

Read the 2023 Gartner® Critical Capabilities for Full Lifecycle API Management report for more details on why Gartner recognized IBM named a Leader.

Use IBM API Connect to secure and manage enterprise APIs throughout their lifecycles. It helps you and your customers consistently create, manage, secure, socialize and monetize enterprise APIs, and is also available as a highly scalable API management platform on IBM Marketplace and AWS.

What is a REST API?

REST API (Representational State Transfer Application Program Interface) is an architectural style that allows software to communicate with other software over a network or on the same device. Most commonly, developers use REST APIs to build web services. Often referred to as RESTful web services, REST uses HTTP methods to retrieve and post data between a client device and a server.

Using the HTTP protocol, REST APIs allow software on one device to talk to software on another device (or the same device) even if they use different operating systems and architectures. The client can ask for resources in a language the server understands, and the server responds with the resource in a language the client can consume. The server returns the resource in either JSON (JavaScript Object Notation), XML (Extensible Markup Language), or text formats, but many APIs support responses in additional languages.

What do we mean by REST architectural style?

REST is a set of governing principles that a developer must adhere to before considering their API “RESTful.” The principles say nothing about how they choose to implement the API.

• Client-server architecture : The API‘s clients use HTTP calls to ask for a resource (a GET method) or send data to the server (a POST method), or any one of the other HTTP methods supported by the API. Although GET and POST are the most frequently used methods, other methods an API may support include HEAD, PUT, PATCH, DELETE, CONNECT, OPTIONS, AND TRACE. The API’s documentation shows the available methods supported by the API. Learn more at w3schools.com
• Stateless : A stateless application does not maintain a connection or store information between requests from the same client. A client makes a request, the API performs the action defined in the request, and responds. Once the API responds, it drops the connection and doesn’t maintain any information about the client in active memory. The API treats each request as the first request.
• Cacheable : A REST API should allow caching of frequently requested data. To reduce bandwidth, latency, and server load, an API should identify cacheable resources, who can cache them, and for how long they can remain in the cache.
• Uniform interface : The defined way a client interacts with the server independent of the device or application.
• Resource-Based : The API needs to have a specific URI (uniform resource identifier) for each resource, such as /monitor/{monitorGuid} from Uptrends API version 4 .
• Self-describing : Includes metadata such as Content-Type that describes how to process the response. Learn more about MIME types.
• HATEOAS (hypermedia as the engine of application state): The server response includes the URI for additional methods the client can access using the response data. Learn more about HATEOAS .
• Layered system : An API may have multiple layers such as proxy servers or load balancers, and the endpoint server may deploy additional servers to formulate a response. The client is unaware of which server responds to the request. A layered system makes an API more scalable.
• Code on demand : Optionally, the API may send executable code such as Java applets or JavaScript.

What is a web resource?

A web resource is basically anything that a client can interact with on the web. The term may apply to a file such as a Word document, image, HTML, or video, but the resource may be more abstract and include actual things. A resource may also be a service such as Google Maps or financial services.

The API developer decides what formats they support for the response. For example, a server may respond with either JSON, XML, or text. The API should have the ability to format the response based on the needs of the client.

REST API examples

Just about everything that happens over the internet involves APIs. APIs work behind the scenes doing things like validating addresses, processing credit cards, making reservations, or scheduling appointments.

The United States Postal System publishes an API that allows businesses to manage their postal needs such as validating addresses, retrieving zip codes, calculating postage, getting tracking data, generating shipping labels, and scheduling mail pickup.

Macy’s department stores offer an API to partners to do things such as searching Macy’s inventory, interacting with gift registries, checking store events, and getting coupons.

AMC Theaters’ API enables developers of third-party apps to access their reservation system where the app can access showtimes, purchase tickets, and order concessions.

Facebook’s Graph API makes it possible for applications to interact with the Facebook application, including making posts, managing ads, and gathering data.

One thing to remember it isn’t uncommon for one API to use another API. For example, AMC Theaters’ API listed above uses another API for processing credit card payments.

Maintaining API availability and speed

API users depend on the APIs for their websites, apps, and devices to work correctly. Unavailable and slow APIs cause failures and frustrates users. Both API providers and consumers need to monitor for problems and act quickly in the event of an outage or a decline in performance.

Monitoring for API uptime

Even a short outage can cause website, app, and device failures. API publishers need to take great care to ensure the system has the necessary redundancy to avoid downtime, but outages still happen. Publishers of an API have a responsibility to their users to make sure that the API responds uninterruptedly to those that use it. Those that rely on APIs should protect their business and users by monitoring APIs critical to their service. Synthetic API monitoring offers two solutions: Multi-Step API Monitoring and Web Service Uptime monitoring .

Checking for basic API availability and performance

To monitor for accurate uptime requires frequent tests. For maintaining high availability, tests should happen once per minute. A simple HTTPS/HTTP web service monitor is a perfect solution for checking availability.

• Check every minute
• Check externally from various worldwide locations
• Check for basic authentication
• Check for response time
• Check response for content
• Check for specific response codes

Uptime monitoring gives assurance that an API responds to request and how long the response takes. Using a content check and checking the response code reveals if the API responded with the expected result. In the case of an error, the alerting system notifies the team about the problem. Also, the monitor reports provide the data to back up any service level agreements.

Setting up web service monitors for every endpoint ensures they remain available, but endpoint checks may not be enough to prove an API functions properly. Multi-step API Monitoring can handle more complicated API checks.

Advanced API Monitoring

Thoroughly testing an API may require something that can handle more complicated scenarios such as those that require redirects, data validation, and data reuse. Multi-Step API Monitoring takes availability monitoring to the next level.

• Manage redirects
• Supports basic, NTLM (Windows), and digest authentication
• Use client certificates
• Declare variables : predefined, assign values from the response body, use automatic variables
• Reuse values in later requests
• Use comparison operators and make assertions on response content and performance
• Capture any numeric response values for reporting

Multi-Step API monitoring allows for the checking of API transactions for full functionality, provides performance data for the entire transaction, and with added assertions, tracks speed for individual requests.

• REST API is an architectural style that lets software talk to other software regardless of operating systems.
• REST APIs support a client/server relationship by providing a uniform interface.
• A REST API’s uniform interface is resourced-based, self-describing, and uses HATEOAS.
• HATEOAS (hypermedia as the engine of application state) means the API response includes information about other available methods using the data received.
• REST APIs are stateless , meaning the server doesn’t maintain connections or sessions between calls.
• REST APIs are multi-layered systems to promote scalability.
• Maintaining high availability and fast responses are critical for a REST API.
• API Monitoring tracks uptime and performance and sends notifications when the API has problems.
• Web Service HTTPS/HTTP monitors are excellent for monitoring uptime.
• Multi-Step API Monitoring verifies complete API interactions for availability, function, and performance.

Try Uptrends for Free

See how Uptrends API Monitoring can help you monitor your APIs and more with a free 30-day trial. No credit card needed!

Understanding REST APIs: Key Principles & Best Practices Explained

Uniform Interface

Rest apis are stateless, client-server design pattern, layered system, stateful and stateless protocols, limitations of stateful apis, why are rest apis stateless, use json with rest apis, use nouns instead of verbs in url, rest apis error handling, well-compiled documentation, allow sorting, filtering, and pagination, understanding rest apis; the bottom line.

REST APIs dominate API development today. Most of the APIs are developed using the REST architecture for a variety of reasons, such as simplified development, easy to understand architecture, great support available online, and wide acceptance from developers and organizations around the world. In this article, we’ll discuss what makes REST APIs so popular, along with their salient features.

REST (representational state transfer) is an architectural style that defines certain constraints to be followed in web service development. A REST API is an application programming interface that obeys REST constraints and therefore enables seamless communication with RESTful web services. REST is simple, flexible, and requires less bandwidth, making it ideal for usage on the internet. All communication done via the REST API uses only HTTP requests.

In this blog, we will help you develop your understanding of REST APIs by explaining the key principles, best practices as well as limitations of stateless APIs.

5 Key Principles of REST APIs

REST imposes certain architectural constraints on APIs. The five major guiding principles or constraints of REST are: uniform interface, stateless, cacheable, client-server, and layered system.

This is a fundamental principle for the design of any RESTful API. There should be a uniform and standard way of interacting with a given server for all client types. The uniform interface helps to simplify the overall architecture of the system.

The constraints that help achieve this include:

Identification of resources: Every system resource should be uniquely identifiable, by using a Uniform Resource Identifier (URI).

Manipulation of resources through representations: Clients should get a uniform representation of a resource that contains enough information to modify the resource's state in the server, as long as they have the required permissions.

Self-descriptive messages: Every resource representation should provide enough information for the client to know how to process it further, such as additional actions that can be performed on the resource.

Hypermedia as the engine of application state (HATEOAS): Clients should have enough information, in the form of hyperlinks, to dynamically discover other resources and drive other interactions.

REST architecture mandates that the server will not store anything related to a session. The server should process and complete each request independently. Each client request should contain all of the information necessary for understanding, processing, and completing it. Clients can do this via query parameters, headers, URIs, request body, etc. This principle of stateless versus stateful web app design will be discussed in more detail below.

Every response sent by the server should contain information regarding its cacheability. Simply, the clients should be able to determine whether or not this response can be cached from their side, and if so, for how long. If a response is cacheable, the client has the right to return the data from its cache for an equivalent request and specified period, without sending another request to the server. A well-managed caching mechanism greatly improves the availability and performance of an API by completely or partially eliminating some of the client-server interactions. However, this increases the chances of users receiving stale data.

REST architecture imposes the client-server design pattern, which enforces the separation of concerns and helps the client and server function independently. In REST, a client is an entity that requests a resource. A server is an entity responsible for storing these resources, having business logic, and sending the response to the client. In many cases, one server (API) can have multiple clients using different client-side technologies, or even other servers that act as a client of the API.

An application with layered architecture is composed of various hierarchical layers. Each layer has information from only itself, and no other layer. There can be multiple intermediate layers between the client and server. You can design your REST APIs with multiple layers, each having tasks such as security, business logic, and application, all working together to fulfill client requests. These layers are invisible to the client and only interact with intermediate servers. This architecture improves the overall system availability and performance by enabling load balancing and shared caches.

Instantly generate production-ready backend Never waste time on repetitive coding again. Try Now

We have already discussed what stateless protocol is. Now let’s discuss stateful protocol. The main difference between stateful and stateless protocol is that in stateful protocol, the server maintains the state of its sessions (e.g., authentication sessions or the client’s previous requests). This information can be used repeatedly for future requests. The same server is used to serve each request in a session. This means that when using stateful protocols, we should always consider the cost associated with it. Also, this is one reason why stateful is not recommended for modern applications.

The stateful protocol does comes with some serious limitations and disadvantages:

Requires storage , since the stateful protocol stores session data, in-memory storage or a database is required to store these sessions. If we use in-memory storage, then requests from the same sessions must be sent to the same server every time. Also, if that server is down, all the session data is lost, and subsequent requests from the same session can’t be served.

Heavily dependent on the server-side state , because if the server loses the stored information, the request cannot be correctly processed.

Backing storage is often needed because of this server-side state dependence.

Overall performance decreases if the session is not efficiently managed.

Scaling a stateful API is a complex and difficult process, as the state of some of the requests might be stored on a particular server. Therefore, we need subsequent requests from the same client to go to the same server. This makes load balancing of requests more difficult as well.

As discussed above, one constraint of REST API architecture is that it must be stateless. Stateless APIs offer multiple advantages:

Helps improve the scalability of APIs to millions of concurrent users: Statelessness in REST achieves this by deploying the same API to multiple servers. Any server can handle any request, since there is no session-related dependency on the server.

Easy to design, implement, and manage: The stateless and uniform interface property helps in this, as fewer complications arise due to stateful property.

Flexible and portable: Data can be migrated between servers, and underlying databases can be changed without affecting the client’s request or response.

Client and server are independent: Due to the stateless property of REST, the developers can work independently on the client and server side.

No need for server-side synchronization logic: This makes the stateless API less complex.

Easy to cache: Clients don't need to worry about the possibility of the state from a previous request affecting the caching ability of the current request. This improves the application’s performance.

Less costly: There is no need for memory allocation and backing storage.

Best Practices for Adopting REST APIs

REST has been widely adopted as a popular architecture style for the development of APIs. Developers around the world have widely accepted certain best practices, which we’ll discuss below.

Always try to use JSON as the format for representation of resources and in sending requests as well. JSON is highly intuitive, and most languages have pre-built functions or libraries to parse and manipulate JSON objects. Many frameworks use JSON as an intermediary format to transfer data and provide converters or mappers to translate JSON into their application’s native format and back to JSON from it. Most of the popular languages such as Python, Java, C++ have internal or external libraries that can read and write JSON data.

Always use nouns that represent a resource of your application. These resources are business entities such as users, customers, and products. Instead of using verbs like create-post or delete-user, use nouns in endpoints and leverage HTTP methods such as GET , POST , PUT , DELETE , to perform operations on the resources.

For example: To operate a basic Create, Retrieve, Update, Delete (CRUD) operation on an entity user, we can use the following endpoints and methods instead of create-user, delete-user.

Endpoint: example.com/user Method: GET Operation: Get details of all users

Endpoint: example.com/user/{name} Method: GET Operation: Get details of a user with a particular name

Endpoint: example.com/user Method: POST Operation: Create a new user

To avoid any confusion and unnecessary complexity, errors should be gracefully handled with proper HTTP return codes such as 401, 403, and 500 to indicate the kind of error that has occurred, along with a message stating the reason this error could have occurred. This allows users to better understand what went wrong with the request.

Documentation is a key aspect of any API. It is the first thing that the user sees. If it is not well compiled in a systematic way and with proper flow, clients will be discouraged from using it. The OpenAPI or Swagger are both well-known, industry-wide accepted formats for defining REST APIs. They facilitate proper documentation of REST APIs for developers.

The data for a resource can be huge, resulting in clients fetching large volumes of data when only a subset of the data is required. Always allow filtering and pagination of data so that only a certain volume of data is passed on with each response. The clients can make requests for more data.

While there are other options like the trending technology of GraphQL, REST APIs are already de facto standard and dominate the API market. Their flexibility, portability, and scalability make them an ideal choice for large enterprise APIs. Amplication is one of them. Our backend development platform helps you to generate production-ready REST APIs automatically including authentication, auto generates endpoints based on best practices, pagination, sorting, filtering, error handling and more. This means you don’t end up stuck in the structural aspects of an application, enabling you to focus on functionality and performance instead.

• RestCase - Manage REST API Development
• REST API Error Codes 101
• Visual API Designer

RESTful API Basic Guidelines

Your data model has started to stabilize and you're in a position to create a public API for your web app or your device.

You realize it's hard to make significant changes to your API once it's released and want to get as much right as possible up front. Now, the internet has no shortage on opinions on API design.

But, since there's no one widely adopted standard that works in all cases, you're left with a bunch of choices: What formats should you accept? How should you authenticate? Should your API be versioned?

Let's first start with the basic guidelines...

What Is REST?

Representational State Transfer (REST) is a technical description of how the World Wide Web works. If to imagine that the Web is a device, and it could have an operating system, its architectural style would be REST. A REST Application Programming Interface (REST API) is a type of web server that enables a user-operated or automated clients, to access resources that model a system’s data and functions. A well-designed REST API entice developers to use the web service and is today a must-have feature. But how to clearly define that the API is actually REST? Such kind of architecture describes six constraints, and we are going to describe them below in this article.

Uniform Interface

The uniform interface that any REST services must provide is fundamental to its design.

Its constraint defines the interface between clients and servers. The four guiding principles of the uniform interface are:

Resource-Based : Individual resources are defined in requests using URIs as resource identifiers and are separate from the responses that are returned to the client.

Actions on Resources Through Representations : When a client gets a representation of a resource, including any metadata attached, it has enough information to customize or delete the resource on the server, if it has permission to do so.

Self-descriptive Messages : Each message includes a precise information that describes how to process it. The responses also clearly indicate their cache-ability.

Hypermedia as the Engine of Application State ( HATEOAS ) : Clients deliver the state via body contents, query-string parameters, request headers and the requested URI. Services deliver state to clients via body content, response codes, and response headers.

Client-Server

The uniform interface divides clients from servers. This means that, for instance, clients are not concerned with data storage, which remains internal to each server, so that the portability of client code is improved. Servers are not engaged with the user interface or user state so they can be simpler and more scalable. Servers and clients may also be replaced and developed independently, as long as the interface is not modified. Most imporantly here is to have the interface intact, one may also give your clients an online REST API documentation or mocking your REST APIs to help the clients to start connecting.

The necessary state to operate the request is contained within it as a part of the URI, query-string parameters, body, or headers. The URI identifies the resource, and the body contains the state of it. Therefore, after the server does its processing, the appropriate state, or the pieces of it communicates back to the client via headers, status and response body.

As the clients can cache responses, they need to be implicitly or explicitly defined as cacheable or not to prevent clients from reusing state or inappropriate data in response to further requests. Well-managed caching partially or completely eliminates some client–server interactions and improves the performance.

Get an invitation to RestCase private beta

Microservices.

Microservices or Layered system where client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way. Mediate servers or API Gateways may improve system scalability by enabling load-balancing and by providing shared caches. Layers also enforce security policies.

Code on Demand

Servers are able to temporarily extend or customize the functionality of a client by transferring logic to it that it can execute. Examples of this may include compiled components such as Java applets and client-side scripts such as JavaScript. This is the only constraint out of six that is optional.

Getting RESTful API versioning right can have a major impact on the how your API is perceived by your API consumers internally or externally, and can also make the management of your API estate more difficult if it’s ill conceived.

Versioning is therefore an important part of a style guide and it’s probably more important to create a policy exhaustively across your organization; if all teams took different approaches as they might in an autonomous model, managing dependencies between APIs across your organization will become very difficult indeed.

A versioning policy should therefore be defined top-down, with clear guidelines on when and why to version your APIs. Any flexibility should be granted to teams in the how, allowing them to implement version requests as they see fit (in custom headers, the Accept header or as part of the URI).

REST API building blocks:

Here are probably the most important the fundamental building blocks of an API:

• Resources (URIs)
• HTTP methods
• HTTP headers
• Query parameters
• Return codes

Anyone who looks at these five areas and are experts in HTTP and REST APIs would argue that all of these are designed for specific purposes and clearly should only be used with those purposes in mind.

However, it’s quite possible that many developers creating your API won’t know (and in some cases won’t really care) about the distinctions or the fundamental principles of REST.

The job of the style guide or RESTful API documentation both for developers and your customers (but mainly guidelines for the developers) is therefore to detail when and how to use each of these: It limits interpretation where limits need to be set. An example set of guidelines might be:

• Resources should describe the “objects” that your API describes, with an identifier that uniquely identifies each object.
• HTTP methods are used to “change” the state of the object, with a mandated list of supported methods.
• HTTP headers are used for passing mandatory arguments such as for authentication, accepted content types, etc.
• Query parameters are used for optional arguments or filtering (searching) and can be omitted as required.
• Return codes should mirror the meaning and semantics of the core HTTP specification, ensuring the code is informative and embellished with extra information in the payload where required.

The idea of such guidelines is therefore to clearly layout for developers how to treat each of these types of construct: To define what it is for and how to implement it.

The more authoritarian style guides will dive into areas such as exact resource constructs and allowed HTTP headers, therefore leaving little doubt in the developer’s mind.

The conclusion is that violating any constraint other than Code on Demand means that service is not strictly RESTful. Complying with all constraints, and thus conforming to the REST architectural style, will enable any kind of distributed hypermedia system to have desirable emergent properties, such as performance, scalability, simplicity, modifiability, visibility, portability and reliability .

Further Reading: * Paypal API Style Guide * Microsoft REST API Guidelines

Some results uranium dioxide powder structure investigation

• Processes of Obtaining and Properties of Powders
• Published: 28 June 2009
• Volume 50 , pages 281–285, ( 2009 )

Cite this article

• E. I. Andreev 1 ,
• K. V. Glavin 2 ,
• A. V. Ivanov 3 ,
• V. V. Malovik 3 ,
• V. V. Martynov 3 &
• V. S. Panov 2  

116 Accesses

7 Citations

Explore all metrics

Features of the macrostructure and microstructure of uranium dioxide powders are considered. Assumptions are made on the mechanisms of the behavior of powders of various natures during pelletizing. Experimental data that reflect the effect of these powders on the quality of fuel pellets, which is evaluated by modern procedures, are presented. To investigate the structure of the powders, modern methods of electron microscopy, helium pycnometry, etc., are used. The presented results indicate the disadvantages of wet methods for obtaining the starting UO 2 powders by the ammonium diuranate (ADU) flow sheet because strong agglomerates and conglomerates, which complicate the process of pelletizing, are formed. The main directions of investigation that can lead to understanding the regularities of formation of the structure of starting UO 2 powders, which will allow one to control the process of their fabrication and stabilize the properties of powders and pellets, are emphasized.

This is a preview of subscription content, log in via an institution to check access.

Access this article

Price includes VAT (Russian Federation)

Instant access to the full article PDF.

Rent this article via DeepDyve

Institutional subscriptions

Similar content being viewed by others

Investigation of the Properties of Uranium-Molybdenum Pellet Fuel for VVER

Investigation of the Influence of the Energy of Thermal Plasma on the Morphology and Phase Composition of Aluminosilicate Microspheres

Evaluation of the possibility of fabricating uranium-molybdenum fuel for vver by powder metallurgy methods.

Patlazhan, S.A., Poristost’ i mikrostruktura sluchainykh upakovok tverdykh sharov raznykh razmerov (Porosity and Microstructure of Chaotic Packings of Solid Spheres of Different Sizes), Chernogolovka: IKhF RAN, 1993.

Google Scholar  

Andreev, E.I., Bocharov, A.S., Ivanov, A.V., et al., Izv. Vyssh. Uchebn. Zaved., Tsvetn. Metall. , 2003, no. 1, p. 48.

Assmann, H., Dörr, W., and Peehs, M., “Control of HO 2 Microstructure by Oxidative Sintering,” J. Nucl. Mater. , 1986, vol. 140,issue 1, pp. 1–6.

Article   ADS   CAS   Google Scholar  

Download references

Author information

Authors and affiliations.

Elektrostal’ Polytechnical Institute (Branch), Moscow Institute of Steel and Alloys, ul. Pervomaiskaya 7, Elektrostal’, Moscow oblast, 144000, Russia

E. I. Andreev

Moscow Institute of Steel and Alloys (State Technical University), Leninskii pr. 4, Moscow, 119049, Russia

K. V. Glavin & V. S. Panov

JSC “Mashinostroitelny Zavod”, ul. K. Marksa 12, Elektrostal’, Moscow oblast, 144001, Russia

A. V. Ivanov, V. V. Malovik & V. V. Martynov

You can also search for this author in PubMed   Google Scholar

Corresponding author

Correspondence to K. V. Glavin .

Additional information

Original Russian Text © E.I. Andreev, K.V. Glavin, A.V. Ivanov, V.V. Malovik, V.V. Martynov, V.S. Panov, 2009, published in Izvestiya VUZ. Poroshkovaya Metallurgiya i Funktsional’nye Pokrytiya, 2008, No. 4, pp. 19–24.

About this article

Andreev, E.I., Glavin, K.V., Ivanov, A.V. et al. Some results uranium dioxide powder structure investigation. Russ. J. Non-ferrous Metals 50 , 281–285 (2009). https://doi.org/10.3103/S1067821209030183

Download citation

Published : 28 June 2009

Issue Date : June 2009

DOI : https://doi.org/10.3103/S1067821209030183

Share this article

Anyone you share the following link with will be able to read this content:

Sorry, a shareable link is not currently available for this article.

Provided by the Springer Nature SharedIt content-sharing initiative

• nuclear fuel
• uranium dioxide
• uranium protoxide-oxide
• crystallite
• agglomerate
• conglomerate
• surface morphology
• ADU-ammonium diuranate
• Find a journal
• Publish with us
• Track your research