REST API

REST API v1

Schema

All API access is over HTTP(S) and all data sent and received as JSON.

$ curl -i https://localhost:8080/api

HTTP/1.1 200 OK
Content-Type: application/json
Status: 200 OK
Content-Length: 2
{}

TBC: All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Resources

Client Errors

There are three possible types of client errors on API calls that receive request bodies:

1. Sending invalid JSON will result in a 400 Bad Request response.

    HTTP/1.1 400 Bad Request
    Content-Length: 35
   
    {"message":"Problems parsing JSON"}
   

2. Sending the wrong type of JSON values will result in a 400 Bad Request response.

    HTTP/1.1 400 Bad Request
    Content-Length: 40
   
    {"message":"Body should be a JSON Hash"}
   

3. Sending invalid files will result in a 422 Unprocessable Entity response.

    HTTP/1.1 422 Unprocessable Entity
    Content-Length: 149
   
    {
      "message": "Validation Failed",
      "errors": [
        {
          "resource": "Issue",
          "field": "title",
          "code": "missing_field"
        }
      ]
    }
   

All error objects have resource and field properties so that your client can tell what the problem is. There's also an error code to let you know what is wrong with the field. These are the possible validation error codes:

missing : This means a resource does not exist.

missing_field : This means a required field on a resource has not been set.

invalid : This means the formatting of a field is invalid. The documentation for that resource should be able to give you more specific information.

already_exists : This means another resource has the same value as this field. This can happen in resources that must have some unique key (such as Label names).

HTTP Verbs

Where possible, API v3 strives to use appropriate HTTP verbs for each action.

HEAD : Can be issued against any resource to get just the HTTP header info.

GET : Used for retrieving resources.

POST : Used for creating resources, or performing custom actions (such as merging a pull request).

PATCH : Used for updating resources with partial JSON data. For instance, an Issue resource has title and body attributes. A PATCH request may accept one or more of the attributes to update the resource. PATCH is a relatively new and uncommon HTTP verb, so resource endpoints also accept POST requests.

PUT : Used for replacing resources or collections.

DELETE : Used for deleting resources.

Authentication

TBC