RESTful API

Design & Best Practices

Created by Sebastian Müller / sebastian.mueller@red6-es.de / @red6_es

red6 enterprise software GmbH

What is REST?

REST
==
REpresentational State Transfer

The fundamental concept is ...

The resource

What is a resource?

A resource is similar to an object/document instance.

HTTP Methods

HTTP verbs

HTTP method Description
GET Retrieves a list of resources or a specific resource.
PUT / PATCH Updates a resource
POST Creates a new resources
DELETE Deletes a resource.

Examples

  • GET /resources - Retrieves a list of resources
  • GET /resources/{id} - Retrieves a specific resource by ID
  • PUT /resources/{id} - Updates resource by ID
  • PATCH /resources/{id} - Partially updates resource by ID
  • POST /resources - Creates a new resource
  • DELETE /resources/{id} - Deletes resource by ID

Status Codes

The most popular

  • 200 OK – [GET]
  • 201 CREATED – [POST/PUT/PATCH]
  • 204 NO CONTENT – [DELETE]
  • 400 INVALID REQUEST – [POST/PUT/PATCH]
  • 404 NOT FOUND – [*]
  • 500 INTERNAL SERVER ERROR – [*]

URI design

Single resource


GET /persons/12345 HTTP/1.1
Host: pdb.hanse
Content-Type: application/json; charset=utf-8

{
  "id": "12345",
  "firstName": "Max",
  "lastName": "Mustermann"
}

Single resource with relations


GET /persons/12345/addresses HTTP/1.1
Host: pdb.hanse
Content-Type: application/json; charset=utf-8

[{
  "id": "67890",
  "street": "Siegfried-Wedells-Platz",
  "number": "1",
  "city": "Hamburg",
  "zip": "20354"
}]

What about actions?

An example from GitHub's gist API:

  • PUT /gist/{id}/star - Star a gist
  • DELETE /gist/{id}/star - Unstar a gist

What about query parameters?

Query parameters are for like filtiering or sorting.

  • GET /persons?state=inactive - Retrieves a list of inactive persons
  • GET /persons?sort=-priority - Retrieves a list of persons in descending order of priority

Aliases for common queries

For example, the recently updated persons query could be packaged up as:

  • GET /persons/recently_updated

Content-Types

The main formats

  • JSON Format
  • XML Format

Selecting a Representation Format


					curl https://example.com/resources \
   -H "Accept: application/xml"

Versioning

Always version your API

Use URI and header together.

Versioning by URI


						curl https://example.com/v1/resources

Versioning by header


						curl https://example.com/resources \
   -H "Version: v1"

Combined both together


					curl https://example.com/v1/resources \
   -H "Version: 2015-06-02"

The URI has a major version and the header has date based sub-versions.

Authentication

SSL everywhere - all the time

Always use SSL. No exceptions.

A RESTful API should be stateless

This means ...

NO cookies or sessions

Possibilities

  • HTTP Basic Auth
  • OAuth 2
  • Special query parameter (?access_token=xxx)

Good examples

- stripe.com/docs/api

- devcenter.wercker.com/development/api/

- developer.github.com/v3/

Questions?

Thank you! ❤