REST API Guide

What is an API?

Before diving into REST, let's briefly explain what API means. API, or Application Programming Interface, is a way for two programs to speak with each other. The programs can be on the same phone, computer, or on different continents. Although there are many different kinds of APIs, in this guide, we're focusing on online APIs.

Online, or web, APIs, allow applications and servers to communicate over the Internet. For example, the Twitter app on your phone uses an API to connect to Twitter's servers to send and receive updates.

Well written APIs are fast, stable, secure, easy to use, and well documented. Through the evolution of the internet and the web, developers invented various API architectures. Today, the most popular way to design an online API is by following REST principles.

What is REST API?

REST stands for Representational State Transfer. It is a way of organizing online APIs powering most of the modern web. It was first described in a 2000 doctoral dissertation, which defined REST as a style of designing network-based software architectures conforming to several guiding principles.

What is a RESTful API?

An API that conforms to the constraints specified in the definition of REST is called a RESTful API. In practice, not all RESTful API follow the definition to the letter. Most most APIs ignore or half-implement the HATEOAS constraint. Web apps often have a concept of a "user session", keeping information about the user on the server and explictly violating the stateless communication principle.

Still, most RESTful APIs work in similar manner. Aside from following the REST constraints, the term often implies a few other aspects of the API:

• HTTP(S). Although REST doesn't imply using HTTP as the underlying protocol, virtually all RESTful APIs are built on top of it
• JSON or XML. Most modern APIs use the JSON file format for resource representation. Some use XML, or allow the client to choose between both.

The term is also useful to distinguish RESTful APIs from other popular architectural styles:

• SOAP (Simple Object Access Protocol). In contrast to REST, which is an architectural pattern, SOAP is a protocol with precise specification. SOAP uses XML as the data format and is built on top of HTTP. The servers must describe the data objects and allowed methods in detail using Web Services Definition Language (WSDL), which is also based on XML. SOAP is less widely used than REST, but is still sometimes used in governmental and big corporation systems.
• RPC (Remote Procedure Call). A style of APIs where the server defines procedures (code) that the client can invoke. Where in REST the client would use a method on a resource, in RPC the client would ask the server to do something (call a procedure). In practice, many RESTful APIs have some RPC functionality because it is hard to implement all of the client-server communication in purely REST style.
• GraphQL (Graph Query Language). GraphQL is a protocol aiming to address some performance shortcomings of REST. It treats all the resources on the server as nodes in a graph, linked by their relationships to each other. For example a "Book" object in would be linked to an "Author" object. GraphQL provides a means of requesting and modifying multiple nodes in that graph at once. It is a somewhat new protocol but is gaining in popularity.

Read an in-depth comparison of REST and other popular types of API in the Types of web APIs part of this guide.

Is there a difference between a REST API and RESTful API? Not really. The terms are mostly synonymous and refer to the same thing. Sometimes people use REST API for APIs that fully conform to the definition of REST, and RESTful API for APIs that loosely follow it, but in most cases, they can be used interchangibly.

REST vs HTTP

HTTP (HyperText Transfer Protocol) is an internet protocol for client-server communication that powers the web. Every time you're visiting a web page, you're using HTTP. Your browser asks for a web page by issuing a HTTP request, and the server responds by returning the HTTP response.

Although REST, in its definition, is not directly tied to HTTP, RESTful APIs in practice always use HTTP as the underlying protocol implementation.

REST, as an architectural style, grew out of experiences with early HTTP. In turn, REST influenced the development of the protocol, and later versions of HTTP include some features that are directly inspired by REST.

Although we're talking about HTTP, modern web sites and APIs in practice use its secure, encrypted version, HTTPS. HTTPS is normal HTTP, just encrypted so that nobody can snoop in, or alter the communication between the client and the server.

To learn how REST uses HTTP features, read the API Requests and Responses article in this guide.

REST vs CRUD

CRUD refers to Create, Read, Update and Delete, the most basic operations for accessing and manipulating data. It is a way of describing how data access works in databases, user interfaces, and APIs.

In RESTful APIs, CRUD describes the operations that can be done on resources, and maps to HTTP request methods:

• Create (HTTP POST) - create a resource on the server
• Read (HTTP GET) - read a resource, or a collection of resources, from the server
• Update (HTTP PUT and HTTP PATCH) - update a resource on the server
• Delete (HTTP DELETE) - delete a resource from the server

Some API operations can't be neatly mapped to CRUD. For example, following a user on Twitter is an action, not a resource. For such operations, RESTful APIs use RPC-style communication, where the client asks the server to do something outside CRUD. This is usually done using HTTP POST method.

Example of a RESTful API

In this imaginary example, a public library has an API that lets users browse and reserve books. We're ignoring security to keep things simple: in reality, users would first need to log in, and only the admins would have the permission to add, modify or delete books and authors.

The API will allow CRUD operations on the books, and an additional RPC-style method to make or cancel a reservation for a book.

The API would expose (or offer to the client) the following endpoints (resource URLs):

• GET example.com/api/books/ - List all books in the library
• GET example.com/api/books/<book-id> - Get information about the book with ID <book-id>
• POST example.com/api/books/<book-id>/reserve - Make a reservation for a book with the ID <book-id>
• POST example.com/api/books/<book-id>/cancel - Cancel a reservation for a book with the ID <book-id>

Library administrators would also have access to endpoints used to manage books:

• POST example.com/api/books/ - Add a book
• PATCH example.com/api/books/<book-id> - Update information for a book with the ID <book-id>
• DELETE example.com/api/book/<book-id> - Remove a book

To create a book, the client sends a HTTP POST request to example.com/api/book with the resource data in JSON format and metadata in request headers:

{
    "id": "978-1-56619-909-4",
    "title": "The Lord of the Rings",
    "author": "J. R. R. Tolkien",
    "year": 1955
}

The server creates a book and responds to the client with the 200 OK response, again returning the newly-created book data in JSON format.