HTTP and REpresentational State Transfer (REST)

RESTful APIs

  • ORM API using HTTP
  • Client-server - separation of concerns, allows independent evolution of components.
  • Stateless - no session state maintained between requests
  • Layered - Client/Server don’t care if additional layers (e.g. caches, load balancers) are in between.
  • Uniform interface:
    • Resource collections and items within collections: ID in URL
    • Use of HTTP request methods and responses as designed (contrasted with SOAP/WSDL?)
  • Idempotent (hopefully) - same request can be duplicated with equivalent result
  • Cacheable - frequently referenced data can be cached to avoid unnecessary network traffic. Can happen at multiple levels (client, cache in front of server, cached in server, etc.)

Avoid REST anti-patterns

It is unfortunately common to see non-RESTful patterns sneaking into RESTful APIs. The most common of these anti-patterns is turning a REST API endpoint into a SOAP-like endpoint by invoking a remote method call. For example, POST /v1/courses/01ca197f-c00c-4f24-a743-091b62f1d500/register (with a request body containing a JSON document with other information like the identity of the registrant). You can immediately tell this is an anti-pattern because “register” is a verb and RESTful resources should only be nouns.

A good REST pattern

A RESTful approach to the above might be something along the lines of: POST /v1/registrations/ with a body containing:

{
    "data": {
        "type": "registrations",
        "attributes": {
            "uni": "abc1234",
            "status": "pending"
        },
        "relationships": {
            "courses": {
                "data": {
                        "type": "courses",
                        "id": "01ca197f-c00c-4f24-a743-091b62f1d500"
                }
            }
        }
    }
}

A side-effect of this data being added to the Registration Model would be to invoke the registration process. This could be synchronous, returning a final 201 Created status or asynchronous, returning a 202 Accepted perhaps with a Location header indicate the URL to check back at. See more in the REST Cookbook.

Keeping the HTTP RESTful allows us to take full advantage of all that HTTP has to offer including caching, the ability to operate through stateless proxies and so on.

HTTP Requests

Consists of a verb (HTTP method), scheme (http/https), server, port and noun (resource), and query parameters.

e.g. GET https://example.com:8000/api/widgets/123?sort=-name

HTTP Method Action Usual Status Codes
POST create a new item under the resource collection URL. 201 Created
202 Accepted
204 No content
403 Forbidden
404 Not found
409 Conflict
GET read either a collection or item within a collection 200 OK
403, 404
PATCH or PUT update by changing some (or all) the data for a resource 200, 202, 204
403, 404, 409
DELETE delete an item (or collection!) 200, 202, 204
403, 404, 409
OPTIONS obtain metadata about a resource collection or item 200

HATEOAS: Hypermedia As The Engine Of Application State.

Given a starting URL, client app should be able to navigate everything without any separate external documentation of the interface.

Request Body

Usually where longer form parameters or content is POSTed. Content-type header specifies what kind of content is being POSTed, PATCHed or PUT. For our purposes this will be application/json or a variant such as application/vnd.api+json.

Response Body

The response to the request. Can be empty (204 No Content). The response’s Content-type header specifies which of the (possible list of) request’s Accept header content types is provided.

Query Parameters

Usually short parameters to modify a request

Example: GET /api/v1/widgets?sort=-name,+qty

Headers

The HTTP Accepts header lists what (prioritized) content types the requestor will accept: Accept: application/json

The HTTP Content-Type header specifies the format of the response: Content-type: application/json

Authentication and Authorization

The HTTP Authorization header is commonly used for access control. There are 3 main styles:

  1. Authorization: Bearer token header – used with OAuth 2 and REST APIs. Stateless.
  2. Authorization: Basic b64-encoded-user:password header – Common for server-to-server, including REST. Stateless.
  3. Session – Used by conventional browser-based apps with a user at one end. Maintains state across multiple HTTP request/response iterations via session cookies (Set-Cookie response and Cookie request headers)

Our “real” apps will use Bearer tokens. For testing in Django, it can be more convenient to use Basic auth as Bearer tokens have to be refreshed from time-to-time. We’ll see how to configure these below.