Client API information

Client API information

Developers building applications in the Ruby programming language are advised to use the sequencescape-client-api gem as this provides an ActiveModel like interface to the API, hiding much of the complexity. The Low level Sequencescape API page gives a good introduction to some of the API.

The documentation on this page provides information on generally interacting with the API and the following pages go into more detail about interacting with specific areas of the API:

• Registering samples discusses how samples, and their containers, are registered in the system through the sample manifests (this functionality is currently awaiting merging into the core code and can found on this branch).
• Requesting laboratory works details how to make submissions of registered samples for sequencing by the various pipelines that are available in a production environment.

HTTP headers

The following HTTP headers are required to be present in any request sent to the API:

• Accept must always be set to application/json
• Cookie should contain one WTSISignOn or api_key cookie set to the appropriate value to identify the current user. This api key is generated on a per user basis.

The following are optional based on circumstance:

• All HTTP POST and PUT requests must contain Content-Type and it has to be set to application/json. No other content types are accepted by the API.
• X-Sequencescape-Client-ID should be set to the authorisation value specified by the system administrators. This provides extended functionality specific to your requirements that may not be available to other clients.

To be clear, the following is a minimal HTTP GET request:

GET /api/1/ HTTP/1.1
Accept: application/json
Cookie: WTSISignOn=identify_cookie_value

And the following is a minimal HTTP POST request:

POST /api/1/some_path HTTP/1.1
Accept: application/json
Content-Type: json
Cookie: WTSISignOn=identify_cookie_value

{}

## HTTP response codes The following HTTP response codes are returned by the API:

• 200 for all successful HTTP GET and PUT requests
• 201 for a successful HTTP POST request where the resource was created
• 300 if a request results in multiple options
• 301 if the request is redirecting the client
• 404 when a resource cannot be found and will contain a general error body
• 405 if the client is not allowed to perform the HTTP request
• 422 for any HTTP PUT or POST requests that fail due to the content provided by the client
• 500 if the server is in real trouble and will contain a general error body
• 501 if the request failed due to a general error with the client request

JSON

All HTTP responses contain a JSON body. This JSON is either for a resource or an error. The structure of the JSON for resources will be documented at a future date but the errors will either be:

{
  "content": {
    "field1": [ "error1", "error2" ],
    "structure.field2": [ "error3" ]
  }
}

Which describes an error based on the content supplied by the client, indicating that the field1 attribute has two errors, and that the structured field structure.field2 has one. Dotted notation is used where fields are nested in the JSON structure, so structure.field2 refers to the following JSON structure:

{
  "structure": {
    "field2": "this field is in error"
  }
}

Where there is a general error with the API the JSON body will be:

{
  "general": [ "error1", "error2" ]
}

Implying that there were two errors that prevented the request from being fulfilled.

All HTTP POST and PUT requests must include the JSON in the body of their request. Specific documentation describes what attributes in the JSON are required or are optional. That documentation will also detail if the JSON attribute is for an association in which case the JSON body should use UUIDs. For example, if the fleas on a Dog resource is a list of the Flea resources that are related then:

{
  "dog": {
    "fleas": [ "UUID1", "UUID2" ]
  }
}

Would cause the API to assign the resources identified by UUID1 and UUID2 to the Dog resource being updated. The response JSON may either display the fleas information inline, or contain a reference to them through an actions element.