Skip to content

API Architecture

AlpineBits® specifies a REST API designed to support the link:https://en.wikipedia.org/wiki/Client%E2%80%93server_modelclient-server communication model, with a focus on system-to-system communication.

This API is built upon link:https://jsonapi.org/format/1.0/JSON:API v1.0, a specification containing best practices for the implementation of REST APIs that exchange JSON data over HTTP.

AlpineBits® relies on its underlying transport protocol to take care of security issues. Hence the use of HTTPS is REQUIRED.

SERVER and CLIENT Responsibilities

A SERVER MUST be able to handle GET requests on all routes it implements (see the standard’s list of routes).

A SERVER MAY support POST, PATCH, and DELETE requests in order to provide provide resource creation, update, and deletion by CLIENTS.

CLIENT and SERVER MUST observe the prescriptions of this standard when performing or responding to the aforementioned requests, using the appropriate headers, message formats.

SERVERS are RECOMMENDED to document their own implementations of the AlpineBits® standard as OpenAPI-based documentations.

Messages

A message is a request sent from a CLIENT to a SERVER, or a response sent from a SERVER to a CLIENT.

CLIENTS and SERVERS MUST include the header Content-Type: application/vnd.api+json without any media type parameters to all messages that include a body. This requirement is designed to accommodate future versions and extensions of JSON:API.

All data exchanged between CLIENTS and SERVERS MUST be in the JSON format conforming to the link:https://jsonapi.org/format/1.0/JSON:API v1.0 standard.

All messages containing a body MUST be encoded in UTF-8.

Messages can be either request messages, success messages, or error messages. The remainder or this section describes the details of each.

Request Messages

Requests sent from a CLIENT to a SERVER are referred to as request messages.

A CLIENT MUST include the header Accept: application/vnd.api+json at least once and without any media type parameters in all requests to a SERVER to represent that the expected response MUST be conformant to this standard.

A SERVER MAY support additional media types, such as application/json and application/xml, but their adoption is not regulated by this standard.

GET /2022-04/events HTTP/1.1
Accept: application/vnd.api+json

GET /2022-04/events HTTP/1.1
Accept: application/vnd.api+json, application/vnd.api+json;modified-parameter=value, application/json

Depending on the related request, a CLIENT MAY include a JSON body on a request message (see ???). This body MUST contain one of the following fields:

  • data: a resource object the CLIENT wishes to create or update. The field MUST is present in certain successful CLIENT requests and SERVER responses (see ???).

When present, a CLIENT MAY include the following fields to a request message:

  • jsonapi: an object describing the JSON:API v1.0 the message it complies to. This field is OPTIONAL and, if set, it MUST be equal to the following object:
    {
  "version": "1.0"
}

The examples below present the basic structure of a request message which varies according to the context they are used in, as described in ???.

GET /2022-04/events HTTP/1.1
Accept: application/vnd.api+json

POST /2022-04/events HTTP/1.1
Content-Type: application/vnd.api+json

{ "jsonapi": { "version": "1.0" }, "data": { "id": …​, "type": "events", …​ } }

A CLIENT MUST NOT include additional fields in data messages, such as links, meta, or included.

A SERVER MUST reject requests including a body when it is not supported (see ???).

A SERVER SHOULD ignore additional fields sent by a CLIENT on a data message.

Success Messages

Successful responses sent from a SERVER to a CLIENT are referred to as success messages.

A success message header MUST contain an HTTP status code in the class https://tools.ietf.org/html/rfc7231#section-6.32xx Success, as in:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

Depending on the related request, a SERVER MAY include a JSON body on a success message (see ???). This body MUST contain one of the following fields:

  • data: a field containing the resource objects to be sent to the CLIENT. The data field MUST be either:

    • if the request expects a collection of resource objects in the response, the data field MUST be an array that contains the expected resources or is empty

    • if the request expects a single resource object in the response, the data field MUST be a single resource object or null

      For details on the different types of resources in this standard and their inner structure, refer to ???.

  • links: an object containing links for navigating the API. Examples of links include self-referencing links, links to resources in relationships, pagination links (see ???), and hypermedia links (see Hypermedia Controls).

    Besides the root of a message, the links object MUST also be present in the root of resource objects and in relationships of resources when these are sent from a SERVER to a CLIENT. Refer to Hypermedia Controls for more details.

  • meta: an object containing the message’s metadata. Examples of metadata include the number of resources available in a certain route (see the count and page fields in ???).

When present, a SERVER MAY include the following fields to a success message:

  • jsonapi: an object describing the JSON:API v1.0 the message it complies to. This field is OPTIONAL and, if set, it MUST be equal to the following object:

    {
  "version": "1.0"
}

  • included: an array of resource objects listed in selected relationships of the resources present in the data field. This field is optional but non-nullable.

    See ??? for more details on the resource inclusion feature.

Success messages SHALL NOT have fields in addition to those listed above.

The example below presents the basic structure of a success message from a SERVER to a CLIENT. The structure of messages vary according to the context they are used, as described in ???.

{
  "jsonapi": {
    "version": "1.0"
  },
  "meta": { ... },
  "links": { ... },
  "data": [ ... ],
  "included": [ ... ]
}

A SERVER MUST reply with specific status codes in the following cases:

  • 200 OK: when the CLIENT’s request has been successfully processed, with the exceptions of:

    • creation requests

    • deletion requests

  • 201 Created: when the CLIENT’s creation request has been successfully processed

  • 204 No Content: when the CLIENT’s deletion request has been successfully processed

Error Messages

An error message results from an unsuccessful request made to a SERVER, regardless of the different contexts detailed in ???.

An error message header MUST contain an HTTP status code either in the class \https://tools.ietf.org/html/rfc7231#section-6.5[Client Error 4xx] or the class \https://tools.ietf.org/html/rfc7231#section-6.6[Server Error 5xx], as in:

HTTP/1.1 401 Unauthorized

If a request message results in multiple errors, the returned status code MUST be the most general status code applicable. For example, if a request results in the errors 415 Unsupported Media Type and 410 Gone, the header SHOULD contain the error code 400 Bad Request.

A SERVER MAY include a body in an error message. If it does, this body MUST contain one of the following fields:

  • errors: an array of link:https://jsonapi.org/format/1.0/#error-objectserror objects as defined in JSON:API v1.0. This field cannot be empty.

  • links: an object containing links (see Hypermedia Controls). This field must contain a self link contain the route present in the CLIENT’s.

When present, a SERVER MAY include the following fields to a error message:

  • jsonapi: an object describing the JSON:API v1.0 the message is complies to. This field is OPTIONAL and, if set, it MUST be equal to the following object:

    {
  "version": "1.0"
}

  • meta: an object that contains non-standard meta-information about its container. This field is OPTIONAL but cannot be empty.

Error messages SHALL NOT have fields in addition to those listed above.

An overview of the basic structure of an error message body is depicted below:

{
  "jsonapi": {
    "version": "1.0"
  },
  "meta": { ... },
  "errors": [
    {
      "status": "404",
      "title": "Endpoint not available"
    }
  ],
  "links": { ... }
}

The following example presents an error message (header and body) containing multiple error objects.

HTTP/1.1 404 Not Found
Content-Type: application/vnd.api+json

{ "jsonapi": { "version": "1.0" }, "errors": [ { "status": 404, "title": "Resource not found." }, { "status": 405, "title": "Method not supported." } ] }

A SERVER MUST reply with specific status codes in the following cases:

  • 400 Bad Request: when a CLIENT makes a request containing:

    • a method body when it is not supposed to (see ???)

    • a query parameter not defined in this standard

    • a query parameter not supported for the specific request

    • a query parameter with an incorrect value

    • conflicting query parameters

    • a method that does not comply the standard’s definitions

    • a method that requests the creation of a resource with an id that is already used or malformed

    • a creation or update of a resources' relationship referring to a resource that does not exist

  • 401 Unauthorized: when a CLIENT makes a request:

    • using an authentication method, but the credentials fail to be validated by the SERVER

    • without an authentication method, but the SERVER does not accept such requests

  • 404 Not Found: when a CLIENT makes a request:

    • to an endpoint not defined in this standard

    • to a non-implemented endpoint

    • asking for a non-existing resource

    • asking for a non-existing page number

  • 405 Method Not Allowed: when a CLIENT makes a request using an HTTP method that is not supported by the SERVER.

  • 406 Not Acceptable: when a CLIENT makes a request with an Accept header containing a media type not supported by the SERVER or with encoding parameters in application/vnd.api+json.

Authentication

For authenticated requests, a SERVER MUST support authentication through the basic authentication method. A SERVER MAY support additional authentication methods, such as, OAuth, JSON Web Token, and OpenID Connect, as well as non-authenticated requests.

The following example presents the Authorization header of a request using basic authentication.

GET /2022-04/events HTTP/1.1
Accept: application/vnd.api+json
Authorization: Basic Y2hyaXM6c2VjcmV0

In this example, the value of Authorization contains the string john:secret encoded in base64 (Y2hyaXM6c2VjcmV0), as specified in the basic authentication method.

If a SERVER does support authenticated requests, it MUST respond to unauthorized requests with the 401 Unauthorized status code (see Error Messages). If an error message body is included in the response, the SERVER MAY use an error object to differentiate between requests that lack an authorization header from those that contain invalid credentials.

HTTP/1.1 401 Unauthorized
Content-Type: application/vnd.api+json

{
   "error": [{
      "status": "401",
      "title": "Unauthenticated request"
   }],
   ...
}

HTTP/1.1 401 Unauthorized
Content-Type: application/vnd.api+json

{
   "error": [{
      "status": "401",
      "title": "Invalid credentials"
   }],
   ...
}

Hypermedia Controls

Hypermedia control is a strategy to encode resource navigation and manipulation within the messages exchanged through an API.

The AlpineBits® standard adopts the hypermedia strategy defined in JSON:API v1.0, which is briefly described in the following paragraphs.

To provide hypermedia controls for CLIENTS to navigate the API, a SERVER MUST include a links object according to what is defined in this standard.

A SERVER MUST include a links object with self link to the root of every message representing the link used by CLIENT in the request that generates that response.

{
  "links": {
    "self": "www.example.com/2022-04/events?fields[events]=name,publisher",
    ...
  },
  "data": [ ... ]
  ...
}

A SERVER MUST include a links object with self link to the root of every resource representing its individual resource route (see ???).

{
  "links": { ... },
  "data": [
    {
      "id": "123",
      "type": "events",
      "meta": { ... },
      "links": {
        "self": "www.example.com/2022-04/events/123",
        ...
      },
      "attributes": { ... },
      "relationships": { ... }
    },
    ...
  ]
  ...
}

A SERVER MUST include a links object with related link to every non-null relationship object (alongside the data field) representing the resource relationship route where the related resource(s) are available at (see ???).

{
  "links": { ... },
  "data": [
    {
      "id": "123",
      "type": "events",
      "meta": { ... },
      "links": { ... },
      "attributes": { ... },
      "relationships": {
        "publisher": {
          "data": {
            "id": "456",
            "type": "agents"
          },
          "links": {
            "related": "www.example.com/2022-04/events/123/publisher"
          }
        },
        ...
      }
    },
    ...
  ]
  ...
}

A CLIENT SHOULD NOT include any links objects to its messages. A SERVER MUST ignore any links objects in messages from CLIENTS.

Action Discovery

SERVERS that support additional HTTP methods SHOULD support link:https://jsonapi.org/faq/#how-to-discover-resource-possible-actionsaction discovery.

To do so, a SERVER needs to:

  • Support HEAD requests on all of its endpoints

  • Answer HEAD requests with messages containing an Allow header listing the HTTP methods it supports on the requested endpoint.

The following two snippets exemplify a HEAD request made by a CLIENT and its response sent by a SERVER.

HEAD /2022-04/events HTTP/1.1
Host: \https://example.com/
Authorization: Basic Y2hyaXM6c2VjcmV0

HTTP/1.1 200 OK
Allow: GET,POST,PATCH,DELETE

A response message to a HEAD request message does not contain a body.