What is a REST API?

APIs have emerged as the most common way for programs and devices to interact with each other in modern computing. An API is a set of rules that describes how one program can connect to and then communicate with another. As the name suggests, a REST API transfers on each request the state of any transaction, which has design, performance and resource benefits over other approaches. REST has developed over more than two decades and is a very common approach for service-based and distributed architectures.

A fundamental concept for REST APIs is the resource. A resource is an object with a type, associated data, relationships to other resources and a set of methods that operate on it. It is very similar to the idea of objects in programming, although only a few standard methods are defined, typified by HTTP GET, POST, PUT and DELETE. Resources can exist by themselves or be grouped into collections that are themselves resources.

In modern computing, a common model – also fundamental to REST APIs – is client-server, where a client that needs a resource identifies and communicates with a server that can provide it. Virtually all cloud traffic is managed in this way, as it offers maximum flexibility for multiple clients to access multiple servers. The principle also works well for so-called ‘serverless’ architectures, where a service broker takes the place of a server known to the client.

The REST API architecture began evolving in 1993, when websites for general use started to appear.

The rapid expansion of the Web led to competing proposals for extensions to the original HyperText Transfer Protocol (HTTP). The World Wide Web Consortium (W3C) and the Internet Engineering Task Force (IETF) started work assessing and formalising new versions of HTTP, the HyperText Transfer Language (HTML) and URI standards.

After six years working on HTTP and URI standardisation, researcher Roy Fielding defined REST in 2000, setting the architectural style to verify future developments of Web protocols, and to identify extensions that were a bad match to the Web’s behavioural and performance goals.

Subsequently, REST concepts have proved highly adaptable to the evolution of connected computing. Since 2015, the OpenAPI Initiative, under the sponsorship of the Linux Foundation with members including Google, IBM, Microsoft and PayPal, has created the OpenAPI Specification based on RESTful rules, which publishes machine-readable interface files for describing, producing, consuming and visualising RESTful web services.

Applications implemented based on the OpenAPI interface files can automatically generate documentation of methods, parameters and models. As well as providing an industry focus for standardised headers, codes, resource descriptions and future innovations, the OpenAPI initiative provides tools, reference materials and best practices. These are especially important in creating, verifying and properly using authentication and data security in a RESTful manner, where the OpenAPI Initiative has a particular focus.

1. Uniform interface

All requests made via a REST API must respect that API’s formatting rules. No matter what client is making the request, it must put each piece of information where every other client would put it. One example is the URL or Uniform Resource Locator used for identifying resources via HTTP, which is one example of a Uniform Resource Identifier (URI) that can have larger scopes.

2. Client-server separation

REST APIs require that client and server applications are totally independent of each other. The client need only know the full name of the resource it wants in the virtual space permitted by the API. Otherwise, the only knowledge client and server have of each other is that exchanged by API transactions.

3. Statelessness

Each client request must contain all the information needed to process it, and the server need not hold any information about that request once it has been received. There is no concept of a session in REST API design and the server is stateless with respect to any particular client.

4. Cacheability

In contrast to the per-client statelessness of the server, resources should be cacheable at one or more points within or between client and server. In the case of the server, if a particular resource has been served, and it is likely to be requested again within a certain time, it should be cached for a more rapid subsequent response. The client should make a similar decision about resources received. The server should indicate via the API whether a resource can be safely cached locally at the client, including the lifetime of the data, where appropriate. Cache design, although not part of a RESTful API specification, is critical to performance and API designers should be aware of how this may apply in practice.

5. Layered system architecture

A consequence of client-server separation, statelessness and cacheability is that a client can make no assumptions about whether it is communicating directly with a server holding a particular resource, or whether it is being served by an intermediate such as a service broker, load balancer,content delivery system or other subsystem closer to the client than the server. This provides system and infrastructure designers considerable flexibility to maximise the efficiency and reliability of request satisfaction across the global wired and wireless infrastructure. It underlies the functionality of edge computing.

6. Code on demand

While REST APIs can and frequently do serve only data for consumption by the client, it is increasingly common for code to be delivered to run on the client, such as Java objects or Javascript web apps. If this is implemented, then such code can only be run on demand by the client.

REST APIs can handle virtually any access request, data format, resource control or status messaging, but the statelessness rule means that each request must contain any authentication needed to verify the request, the precise definition of the resource required and the exact action required.

For example, a non-RESTful file system API may respond to a request to read a file by returning a file handle, a small token assigned to a session so that the client can make repeated reads just by reference to that handle. A REST API would instead have to send client authorisation each time but also the full exact resource identifier together with the precise location within the file of the data to read. It’s up to the client to keep track.

REST APIs pass all this information via a combination of headers and parameter fields, and can exchange the actual data in any format. A very common standard is JSON, the Javascript Object Notation format, which despite its name is readable by both humans and machines, by eye or using any of the popular programming languages.

Consideration needs to be given in REST API design for efficiency, especially where large data transfers or time-critical streams are to be handled, or conversely small amounts of data from resource-constrained sources such as IoT systems.

OVHcloud API is a Web service allowing OVHcloud customers to buy, manage, upgrade and configure OVHcloud products without using the graphical customer interface. It is based on the latest RESTful API to manage nearly all in the OVHcloud universe. The API is designed to be simple and easy to use, and code snippets are provided in a wide variety of languages.

OVHcloud Manager (V6) is now accessible via the OVHcloud API, and every new product and product version will include API compatibility. The API explorer console can browse the API to discover all available functions by OVHcloud products, even to those not registered as developers. You can also select a product and browse the dedicated API to discover related actions.

Using the OVHcloud RESTful API allows quick, lightweight development of scripts for custom functions, automation, multiple simultaneous tasks and creating IaaS/PaaS deployment and management tools. Explicit language support is available for C, C++, C#, Java, Perl, PHP, Python and Ruby and many more.