REST API

A REST API is a particular kind of [[API]] served over [[HTTP]]. REST stands for REpresentational State Transfer. A REST API is not necessarily just an API served over HTTP, however. Typically, it is a kind of API that conforms to specific standards.

Resources

At the heart of a REST API is resources. Resources can be thought of as objects or types. They are the primary means through which one interacts with a REST API.

A resource is a thing. A blog resource might be represented with the URL path:

/blog

(the domain is omitted)

Verbs

HTTP verbs are a crucial part of a REST API. There are six HTTP verbs:

• GET - retrieves a resource. Idempotent
• POST - creates a resource. Side effects expected
• PUT - updates a resource. Idempotent
• PATCH - updates a resource. Idempotent
• DELETE - deletes a resource. Side effects expected
• OPTIONS - lists actions allowed on a resource. Idempotent

Examples:

GET    /blog/1 - retrieves a blog
GET    /blog   - retrieves a list of blogs
PUT    /blog/1 - with some body, updates blog 1
DELETE /blog/1 - deletes blog 1
POST   /blog   - creates a new blog

Relationships

GET  /blog/1/posts   - retrieves a list of posts
POST /blog/1/posts   - creates a new post for blog 1
PUT  /blog/1/posts/2 - deletes a post.

Links

The next piece of a REST API are links. Links describe relationships between objects.

When a resource is retrieved via a GET, it should return a body of links describing what options are possible with that resource.

{
  "type": "blog",
  "id": 1,
  "name": "first blog",
  "links": {
    "self": "/blog/1",
    "posts": "/blog/1/posts"
  }
}

Metadata

Finally, metadata describes the type information of a resource.

{
  "type": "blog",
  "id": 1,
  "attributes": {
    "name": "foo blog"
  },
  "meta": {
    "type": "blog",
    "attributes": {
      "name": {
        "type": "string",
        "maxLength": 20
      }
    }
  }
}

For any attribute specified on the resource, the meta must describe it.