What is a REST API?
REST APIs provide a flexible, lightweight way to integrate applications and to connect components in microservices architectures
Learn about IBM API management solutions
Black and blue background
What is a REST API?

An API, or application programming interface, is a set of rules that define how applications or devices can connect to and communicate with each other. A REST API is an API that conforms to the design principles of the REST, or representational state transfer architectural style. For this reason, REST APIs are sometimes referred to RESTful APIs.

First defined in 2000 by computer scientist Dr. Roy Fielding in his doctoral dissertation, REST provides a relatively high level of flexibility and freedom for developers. This flexibility is just one reason why REST APIs have emerged as a common method for connecting components and applications in a microservices architecture.

REST design principles

At the most basic level, an API is a mechanism that enables an application or service to access a resource within another application or service. The application or service doing the accessing is called the client, and the application or service containing the resource is called the server.

Some APIs, such as SOAP or XML-RPC, impose a strict framework on developers. But REST APIs can be developed using virtually any programming language and support a variety of data formats. The only requirement is that they align to the following six REST design principles - also known as architectural constraints:

  1. Uniform interface. 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.

  2. Client-server decoupling. In REST API design, client and server applications must be completely independent of each other. The only information 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.

  3. Statelessness. 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.

  4. Cacheability. 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.

  5. Layered system architecture. 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.

  6. Code on demand (optional). 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.
How REST APIs work

REST APIs communicate via 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 to create one, a PUT request to update a record, and a DELETE request to delete 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.


REST API best practices

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 - available endpoints, allowed operations on each endpoint, operation parameters, authentication methods, and other information. The latest version, OAS3 (link resides outside ibm.com), 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, such as using hashing algorithms for password security and HTTPS for secure data transmission. An authorization framework like OAuth 2.0 (link resides outside ibm.com) 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.

Related solutions
IBM Cloud Pak® for Integration

IBM Cloud Pak® for Integration is a hybrid integration platform that applies the functionality of closed-loop AI automation to support multiple styles of integration. 

Explore IBM Cloud Pak® for Integration
IBM API Connect® 

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

Explore IBM API Connect®
IBM Automation®

From your business workflows to your IT operations, we’ve got you covered with AI-powered automation. 

Explore IBM Automation®
iPaaS Solutions

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

Explore IBM iPaaS Solutions
Resources What is an API?

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

Agile integration guide

Download our  agile integration guide, which explores the merits of a container-based, decentralized, microservices-aligned approach for integrating solutions. 

What are microservices?

Microservices architecture is an approach in which a single application is composed of many loosely coupled and independently deployable smaller services.

Take the next step

IBM tools and services can help you address important issues surrounding APIs—including security, governance, and automation—as you continue modernizing your applications. Check out IBM API Connect®  to let architects and admins take full control of the API lifecycle. 

Learn more about IBM API Connect