Concepts

The handful of ideas you need in your head before the rest of the documentation starts to make sense.

Contents

• Resources
• Requests and responses
• State and storage
• Errors

Resources

A resource is anything the server exposes at a stable address, such as a page, a document, or a record. Each resource is identified by a URL path. The same path always refers to the same resource, although its contents may change over time.

Resources are usually grouped into collections. For example, /docs/concepts is a single resource inside the /docs collection.

/docs                 collection of documentation sections
/docs/concepts        a single resource
/docs/concepts#state  a fragment inside that resource

Requests and responses

Every interaction is a request followed by a response. The client sends a method, a path, optional query parameters, and headers. The server replies with a status code, headers, and a body.

GET requests should be safe to repeat. They read data and do not change it.

State and storage

HTTP is stateless. The server does not remember earlier requests unless you give it something to remember with. The common options are:

• Cookies that hold a session identifier.
• A database that stores records shared across all visitors.
• Tokens sent with each request, such as bearer tokens in an Authorization header.

Choosing between them

Use cookies for per-browser state, such as a preferred theme. Use a database for anything that must persist or be shared, such as posts, orders, or accounts.

Errors

Errors are reported with status codes, and the body should explain what went wrong. The most common ones are listed below.