Conventions for REST APIs

The properties of REST APIs

The uniform interface property is achieved by abiding by certain API design conventions. These conventions require the designer to think in terms of resources (nouns) and actions (verbs). A simple example will illustrate the point.

Suppose we’re developing a card catalog. Each book has an author, a title, and an indication of whether it’s been lent out. Typically, we would construct two types of URIsA Uniform Resource Identifier is a unique sequence of characters that identifies a logical or physical resource used by web technologies, also called routes, from the server’s perspective. The first one refers to all books and might be website.com/books/.

The second type refers to a single book and might be website.com/books/9780385333788, where we’ve chosen to use the book’s ISBNInternational Standard Book Number, ISBNs are calculated using a specific mathematical formula and include a check digit to validate the number as its unique identifier. Notice that:

• The list of all books and a specific book are two resources or nouns.

• A single book is just one “book”, but the URI uses the plural “books”. This convention simplifies the connection between the collection and the individual item.

The use of the ISBN is reasonable, since it’s a publicly accepted unique identifier and is available for almost all books. The key point is that each book has a unique and unchanging identifier with which it is accessed.

So what can we do with this resource? The HTTP methods typically used by REST APIs are GET, PUT, POST, and DELETE.

Example of REST API methods