Documents how to write APIs

This API Manifesto is a fast and easy overview of the most important elements for building a rock-solid API, which both the backend and frontend team enjoys working with. APIs are suppose to be very strict, it's a contract between Backend & Frontend. In the same time, there is no reason for APIs to be different depending on which language / framework was used in the Backend.

This is not a full blown manifesto, check the Inspiration section for references to other manifestos with more details.

• API Manifesto
  • Introduction
• Table of Contents
• Requests
  • URLs
    • Prefix API endpoints
    • API versioning
  • Request Headers
    • Protected endpoints
    • Supporting localization
    • Making debugging easier
• Responses
  • Response Body
    • Object at the root level
    • Return an empty collection when there are no results
  • Use null or unset keys that are not set
• Status Codes
• Auth
  • TODO
• Error Handling
• Localization
  • TODO
• Timeouts
  • Client to Server
  • Server to Server
• Pagination
  • TODO
• Inspiration

Prefix API endpoints with /api/ to separate them from other URLs like HTML views served on the same server.

www.example.com/api/v1/products/1

Versioning your API allows you to make non-backwards compatible changes to your API for newer clients by introducing new versions of endpoints while not breaking existing clients.

Include the API version in the URL. Versions start with 1 and are prefixed with v. The version path component should come right after the api path component.

In case of an existing API that doesn't have this versioning scheme but needs a new version, skip v1 and go straight to v2.

We're not recommending to use the headers (typically the Accept header) for versioning. The URL based approach is more obvious, usually simpler to implement, and testing URLs can be done in the browser.

www.example.com/api/v2/auth/login

Accept = "application/vnd.example.v1+json"

After the API prefix and the version comes the part of the URL path that identifies the resource -- the piece of data you are interested in. Refer to a type of resource with a plural noun (eg. "users"). Directly following such a noun can be an identifier that points to a single instance. A resource can also be nested, usually if there some sort of parent/child relationship. This can be expressed by appending another plural noun to the URL.

/api/v1/shops

/api/v1/products/42

/api/v1/posts/1/comments

/api/v1/comments/87

Query parameters are like meta data to the (usually GET) URL request. They can be used when you need more control over what data should be returned. Good use cases include filters and sorting. Some things are better suited for headers, such as providing authentication and indicating the preferred encoding type.

/api/v1/posts?page=2&perPage=10

/api/v1/posts?apiKey=a7dhas8u

HTTP methods are used to indicate what action to perform with the resource.

A GET call is used to retrieve data and should not result in changes to the accessed resource. Multiple identical requests should have the same effect as a single request (idempotency).

POST is used to create new resources.

PATCH requests modify existing resources. Only fields that need to be updated need to be included - all others will be left as they are. In order to "unset" optional properties use null for the value.

With PUT calls we can replace entire objects. Only the database identifier should not be changed.

To delete a resource, use the DELETE method.

A HEAD call must never return a body. It can be used to see if an object exists and to see if a cached value is still up to date.

Use the Authorization header to consume protected endpoints. See the Auth section for more information on how to handle authorization and authentication.

Authorization = "Basic QWxhZGRpbjpPcGVuU2VzYW1l"

UserToken = "QWxhZGRpbjpPcGVuU2VzYW1l"

In order to support localization now and in the future, the Accept-Language should be used to indicate the client's language towards the API.

Accept-Language = "da"

Accept-Language = "da, en"

Accept-Language = "danish"

Use headers to give the API information about the consumer to ease debugging. There's no industry standard, so feel free to make your own convention, just remember to use it consistently.

Client-Meta-Information = iOS;staging;v1.2;iOS12;iPhone13

See:

• N-Meta-Vapor
• N-Meta-PHP
• N-Meta-Laravel

A body should always return an object at the root level. This enables including additional data about the response such as metadata separate from the object(s). We recommend using data for successful requests with meaningful response data and error for unsuccessful requests with error data being returned.

{
    "data": [
        {
            "username": "..."
        },
        {
            "username": "..."
        }
    ]
}

{
    "data": {
        "username": "..."
    }
}

{
    "error": {
        "description": "..."
    }
}

[
    {
        "email": "..."
    },
    {
        "email": "..."
    }
]

{
    "error": true,
    "description": "..."
}

To make it easier for the API consumer, return HTTP status code 200 with an empty collection instead of e.g. 204 with no body.

{
    "data": []
}

In case of missing values return them as null or don't include them. Do not use empty objects or empty strings.

{
    "data": {
        "email": null,
        "name": "..."
    }
}

{
    "data": {
        "name": "..."
    }
}

{
    "data": {
        "name": ""
    }
}

{
    "error": {
        "localizedTitle": "Title goes here", // Optional title localized for end user
        "localizedMessage": "Message goes here", // Optional message localized for end user
        "message": "Invalid format, digits required", // Message for developer
        "isRecoverable": true, // Is the error handled in the UI is fatal or can it be recovered, eg: try again
        "identifier": "PASSWORD_NOT_FOLLOWING_PATTERN", // Identifier which the consumer of the API can parse and switch case on
        "source": "LoginService" // In micro services architecture, you might want to understand what service
    },
    "payload": {
        "validationErrors": [{
            "field": "password",
            "errors": [{
                    "type": "required",
                    "localizedMessage": "Please enter a password"
                },
                {
                    "type": "regex",
                    "localizedMessage": "Password format should have following: 8 characters, 1 small letter, 1 big letter & 1 number"
                },
            ]
        }]
    },
    "metadata": {
        "errorID": "1234-ABC" // Optional ID for if the error is stored in DB, APM, Bug tracking tools like Bugsnag, Sentry, Rollbar, New Relic etc.
    }
}

{
  "error": "Internal server error"
}

Generally APIs should respond in less than 250ms on a wired connection. There needs to be a special reason for exceeding that. Further, it is important to understand that it will be harder and more expensive to scale the backend if response times are high.

It's common that the webserver configuration will timeout the request after 30 or 60 seconds.

Since you never know what network the client is on, if they are in a metro or 100mBit wifi. Response time can vary a lot for several reason. Therefore set timeouts to:

Server to service APIs should always be very stable due to connection being wired and stable. Therefore we can be much more aggressive about timeouts.

These guidelines have been made with inspiration from the following API guidelines:

• Microsoft API Guidelines
• Zalando API Guidelines
• PayPal API Guidelines
• Atlassian API Guidelines
• JSON:API