Basics of REST APIs

Part of the process of building a REST server is constructing an API for that server. A REST API is a collection of HTTP verb, URL pairs along with a specification for any objects that get sent to or from the server as part of the request or response.

In this course we will always be using the JSON format to encode any objects that need to be sent to or from the server in the body of a request or a response. Spring Boot includes automatic support for translating JSON content in a request body into Java objects and support for converting any Java objects we return in responses to JSON.

API design

This document lays out the basics of REST API design. The API design strategies I use are based on standard API design strategies used in industry. As an example of more detailed API design guidelines you can take a look at Google's Cloud API design guide.

HTTP verbs

A REST server uses HTTP as the native communication protocol for all client communication. Every HTTP request starts with an HTTP verb, so knowing what verbs are available and conventions surrounding their use are an essential first step for us.

Below is a table of the most common HTTP verbs, along with their uses.

Verb	Description
GET	Fetch data from the server
POST	Store an object on the server
DELETE	Delete an existing object
PUT	Replace an existing object
PATCH	Update part or all of an existing object

An important distinction here is the distinction between POST, PUT, and PATCH. POST is intended to be used to store completely new entities on the server. In the example we have already seen I used POST to upload new user accounts. The POST request handling code I wrote will reject a new user if their user name matches that of an existing user. PUT and PATCH are intended to update existing entities. For example, if we wanted to update the password of an existing user without changing either their user id or their user name we would use PUT or PATCH. PUT requires us to upload a complete object containing all of the fields of the object we are updating. PATCH, on the other hand, can be used to selectively update only part of an object.

HTTP URL Conventions

The second essential part of an HTTP request is the URL. The URL identifies the specific entity on the server that we are working with. Most of the rest of this documents covers widely used conventions for constructing URLs for a REST application.

The first concept we encounter when working with URLs is the concept of a REST resource. A resource is a specific class of data that we want our server to work with. Every application we construct is going to consist of a small set of primary resources, along with a set of subsidiary resources.

For example, in the auction application two primary resources we are going to work with include users and auctions. Here are some typical examples of resource URLs we would use to work with these classes:

• To post a new object of a given resource type we typically execute a POST directly to that primary resource URL. For example, to POST a new user we POST to the URL /users.
• To get all of the objects of a particular primary resource type we simply do a GET with that primary resource URL. For example, to fetch a list of all of the currently active auctions we can do a GET against the URL /auctions.
• On occasion we may also want to provide a way to filter results. An example of this in the auction system is fetching only those auctions that have a particular tag attached to them. These kinds of queries are typically done by using query parameters to filter the results. For example, to fetch all of the auctions where clothes are for sale we can do a GET with the URL /auctions?tag=clothes.
• To view individual objects of a given primary resource type we construct a URL that ends with a unique identifier for the object we want. For example, to fetch the particular auction whose id is lakjlke-43nh2lk3-newl45 we would do a GET with the URL /auctions/lakjlke-43nh2lk3-newl45. We can use that same URL pattern to delete a particular object or update it with PUT or PATCH.
• Other resources are categorized as subsidiary resources. A subsidiary resource is subsidiary because it depends on some primary resource. For example, in the auction application profiles belong to users and bids are associated with auctions. To access a subsidiary resource we start with a URL that identifies the primary resource and then attach an additional segment to the URL to specify what subsidiary thing we want to access. For example, to fetch the list of all of the bids for a given auction we would do a GET with a URL that takes the form /auctions/<action-id>/bids. We would also use that same URL pattern to POST a new bid for a particular auction.

Remote Procedure Calls

The standard HTTP verbs along with the URL patterns I showed above are usually sufficient to handle most of the interactions needed for a particular API. There are, however, so cases that don't fit into this framework. In some cases we will want to carry out an action that is closer in character to a function call in a conventional programming language.

Here is a fairly obvious example. One of the operations we need to support in our API is the operation of checking whether or not a given user name/password combination is correct and then fetching the user id for that user. In a conventional programming language we would set up a function to check user names and passwords:

String loginCheck(String name,String password)

The function would return the user id for a user, or an empty string if the name or password are incorrect.

Fortunately for us the HTTP protocol is flexible enough to allows us to cobble together something that approximates a function call. Here are main ideas.

1. We start by constructing an object that contains the parameter values. In the case of password checking we would make a JSON object with name and password properties.
2. We then send that parameter object as the body of a POST to a special action URL. For example, to handle password checking we could use an action URL of /users/login.
3. The value that would normally be returned from the function simply gets returned as the body of the response to the POST.