REST

A REST API (Representational State Transfer Application Programming Interface) is a web service that allows different systems to communicate over the internet using standard HTTP methods. It follows the principles of REST architecture, which is designed to be lightweight, scalable, and stateless.

Characteristics of REST APIs

• Stateless – Each request from a client to the server must contain all necessary information because the server does not store client state.

• Client-Server Architecture – The client and server are independent; the client only needs to know the API structure.

• Uniform Interface – Resources (data objects) are accessed via standard HTTP methods:

  • GET – Retrieve data
    The body of the response message contains the details of the requested resource.

  • POST – Create new data
    The body of the request message provides the details of the new resource

  • PUT – Update existing data
    The body of the request message specifies the resource to be created or updated.

  • DELETE – Remove data

• Resource-Based – Data is represented as resources, each with a unique URL (e.g., /users, /products/123).

• Uses Standard Formats – Typically, data is exchanged in JSON or XML format.

• Cacheable – Responses can be cached to improve performance.

Resources

Any information that can be named is a resource. e.g., customers, documents. A resource can be a collection or a single entity.

The URI of the resource

e.g.

/customers delivers a collection of customers
/customers/{customerId} returns a customer out of all cutomers with the given customerId
/customers/{customerId}/accounts returns a collection of accounts of a given customer
/customers/{customerId}/accounts/{accountId} ...

Use nouns for the resources

e.g. Customer, Accounts, ...
Don't use verbs.

Use sub-resources for relations

Try to think of a tree with more and more detailed information to describe the resource.

All customers->one of all customers->all his accounts->one of the accounts-> ...

Use hyphens to increase readability

Long words in URIs are not good to read.

/book-mangement/ordered-books
better than
/bookmangement/orderedbooks

Use HTTP Status codes

Use correct http status codes for the resonses

Provide up-to-date and accurate documentation

Good documentation helps developers use your API. Support OpenAPI for good documentation and code generation.

Versioning

URI Versioning (Path Versioning)

The version number is included in the URL.

Example:

GET https://api.example.com/v1/users

Pros:

• Simple and easy to implement.
• Clear distinction between versions.

Cons:

• Clutters the URL.
• Requires changes in client applications when a new version is released.

Query Parameter Versioning

The version number is passed as a query parameter.

Example:

GET https://api.example.com/users?version=1

Pros:

• Easy to implement without changing the endpoint structure.
• Allows dynamic version selection.

Cons:

• Can be overlooked in API documentation.
• Some caching mechanisms may not work well with query parameters.

Header Versioning

The version is specified in the HTTP headers.

Example:

GET https://api.example.com/users Headers: Accept: application/vnd.example.v1+json

Pros:

• Clean URL structure.
• Works well with content negotiation.

Cons:

• Harder to test/debug (requires setting headers).
• Not as visible as URI versioning.

Media Type Versioning (MIME Type)

The API version is included in the Accept header as a custom media type.

Example:

GET https://api.example.com