Overview

If you setup everything properly, all endpoints should only be accessible viaHTTPSand are located athost:port/api/v1. For example:

https://host:port/api/v1/ping

Response Structure

Every response is contained by the envelope:

{
    "meta": {
        "status": 200,
        "error": {
            "status": 200,
            "type": "...",
            "message": "..."
        }
    },
    "payload": {
        ...
    }
}

Body Meta

The meta key is used to communicate extra information about the response to the developer. If all goes well, you'll only ever see a code key with value200. However, sometimes things go wrong, and in that case you might see a response like:

{
    "meta": {
        "status": 422,
        "error": {
          "status": 422
          "type": "UnprocessableEntity",
          "message": "Unprocessable entity"
        }
    }
}

Body Payload

The response payload object contains the actual information requested (if applicable). For example:

{
    "meta": {
        ...
    },
    "payload": {
        "id": "0daeb184-bd74-4aa9-b4dd-8a9aa2145ace",
        "email": "...",
        "roles": [...]
    }
}

Limits

If you're sending too many requests in a short amount of time, the server will send back a 503 error code (server unavailable). By default you are limited to 15 requests per second per IP.

Request Content-Type

Actions that POST, PUT or PATCH resources over the API must include the corresponding Content-Type header, which for most cases would be either application/json or application/x-www-form-urlencoded.