Travis CI API Docs

Travis CI API Format

This document describes the general format and principles followed by the official Travis CI API version 3.

Status of this Document

This document is under heavy development. The specification might change at any point in time.

Requirements

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Motivation

The API format should be intuitive enough that developers familiar with HTTP and JSON should be able understand it by inspecting its payloads, assuming they are familiar with the business logic exposed by the API.

The aim is to establish a standard format used for both external and internal APIs at Travis CI.

The format tries to lay a foundation for generic client libraries, making it possible to quickly write code interacting with new API endpoints.

JSON Payload

API resources SHOULD use JSON as preferred representation. Resource attributes SHOULD be mapped directly to JSON key/value pairs.

Therefore, the following is a valid resource:

{
  "name": "John Doe",
  "age":  42
}

Any JSON payload may at any time include additional, previously undefined attributes. A client MAY choose to ignore any unknown attributes or expose them. A client SHOULD NOT trigger an error for unknown attributes.

If the representation is encoded as JSON, it MUST return an object. Returning an array at top level is not permitted.

Meta Data

The JSON representation MAY include meta data in form of key/value pairs where the key is prefixed by an @ sign (byte value 64). Only keys defined in this document SHOULD be used. The semantics of meta data keys defined here MUST NOT be changed.

{
  "@type": "user",
  "@href": "/user/John%20Doe",
  "name":  "John Doe",
  "age":   42
}

Meta data MAY also be applied to nested objects.

{
  "@type": "user",
  "@href": "/user/John%20Doe",
  "name":  "John Doe",
  "age":   42,
  "home":  {
    "@type":  "address",
    "city":   "Berlin",
    "street": "Rigaer Str. 8"
  }
}

@type

The JSON representation SHOULD include a @type key at top level, and MAY include this key in any nested objects.

The value of this key identifies the type of the entity represented by the JSON payload. This allows the client to reason about semantics, available operations, and attributes included in different representations of the same entity. This information can be derived from the home document (see below).

@href

Any entity with a URI that returns a JSON representation of itself at top level on a GET request SHOULD include the URI as the @href property. The value can be a relative link.

Entities that occur multiple times in a JSON payload MAY be identified by an object containing nothing but the @href property for all but the first occurrence.

{
  "@type":    "user",
  "@href":    "/user/John%20Doe",
  "name":     "John Doe",
  "age":      42,
  "shipping": {
    "@type":  "address",
    "@href":  "/address/1",
    "city":   "Berlin",
    "street": "Rigaer Str. 8"
  },
  "billing":  {
    "@href":  "/address/1"
  }
}

@pagination

A collection returned by a single response might represent a subset of a larger collection. To retrieve another subset of the larger collection, a client can make use of the metadata exposed in the @pagination field.

{
  "@type":       "users",
  "@href":       "/users?limit=1",
  "@pagination": {
    "limit":     1,
    "offset":    0,
    "count":     42,
    "is_first":  true,
    "is_last":   false,
    "next":      {
      "@href":   "/users?limit=1&offset=1",
      "offset":  1,
      "limit":   1
    },
    "prev":      null,
    "first":     {
      "@href":   "/users?limit=1",
      "offset":  0,
      "limit":   1
    },
    "last":      {
      "@href":   "/users?limit=1&offset=41",
      "offset":  41,
      "limit":   1
    }
  },
  "users":       [
    {
      "@type": "user",
      "@href": "/user/John%20Doe",
      "name":  "John Doe",
      "age":   42
    }
  ]
}

The @pagination object MAY include any of these fields:

Field	Description
limit	maximum number of entries included in the current subset
offset	number of entries preceding the first entry of the subset
count	overall number of entries in the collection
is_first	true if there are no entries before the current subset
is_last	true if there are no entries after the current subset
next	object linking to the next subset, null if there is no next subset
prev	object linking to the previous subset, null if there is no previous subset
first	object linking to the first subset
last	object linking to the last subset

The collections linked to by next, prev, first and last SHOULD only vary in their offset and keep the same limit as the current subset.

@permissions

Any object that includes the @type field MAY also include an @permissions field.

This field itself includes an object mapping keys to boolean values. Each of these fields represents a permission and the boolean value indicates whether the current client has, or does not have, the permission relating to the object the @permissions field is included in.

{
  "@type":        "user",
  "@href":        "/user/John%20Doe",
  "name":         "John Doe",
  "age":          42,
  "@permissions": {
    "call_user":     true,
    "share_contact": false
  }
}

To make proper use of these permissions the client and the server need to have a shared understanding of their semantics.

@representation

Any object that includes the @type field MAY also include an @representation field.

For each entity there MAY be more than one JSON representation. These differ in the fields that are included.

If an object supports multiple representations, it SHOULD include the @representation field. Furthermore, it SHOULD support a standard and a minimal representation.

The standard representation SHOULD be used for objects at top level.

The minimal representation SHOULD a subset of the standard representation, useful when the entity is not the main interest for the client.

Fields included in multiple representations MUST NOT differ in semantics across representations.

Pre-Defined Types

An API following this format can and should define its own types to represent its business objects. However, to allow generic consumers of such APIs to reason on these objects, and on operations they can perform on these objects, a few pre-defined types are required. These types MUST share semantics across implementations.

home

The main entry point, or home document, for an API following this format, SHOULD return an object of the home type at top level. Consumers of the API SHOULD use this object as a reference for any other API request they will perform.

The home object SHOULD contain two fields: resources and errors.

The resources field contains an object mapping type-identifiers to resource descriptions. These identifiers MUST correspond to potential values of the @type field. The resource description MUST be of the resource type.

Any value that an object has as its @type field SHOULD have an entry in the resources field, or be of a pre-defined type.

The errors field contains an object mapping error identifiers to error descriptions. This describes the specific shapes of errors returned by the API. The identifiers represent potential values of the error_type field.

The home object MAY also include additional fields that help clients to reason about the API.