Write API

We expose a simple HTTP API for storing data in the Performance Platform.

There is one endpoint per data-set that can accept one or more JSON records being sent to it via a POST. We use OAuth 2.0 Bearer tokens to authenticate attempts to write to a data set.

You authorize each request by adding an Authorization header with the secret access token you should have been provided for each data-set.

The client request:

  • should use a URL like https://<write-host>/data/<data-group>/<data-type>, where <write-host> could be something like www.performance.service.gov.uk
  • must have an HTTP Content-Type header of application/json
  • must have a valid Authorization header

The backdropsend tool provides a command line interface to the API. This adds support for retrying.

Adding data

POST /data/(string: data_group)/(string: data_type)
Synopsis:Insert data into a data set by sending a POST request with JSON in the body.

Example request:

POST /data/carers-allowance/transaction-count HTTP/1.1
Host: www.performance.service.gov.uk
Authorization: Bearer abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz01
Content-Type: application/json

[
  {
    "_id": "unique-identifier-1",
    "_timestamp": "2015-01-01T00:00:00Z",
    "count": 123
  },
  {
    "_id": "unique-identifier-2",
    "_timestamp": "2015-01-02T00:00:00Z",
    "count": 456
  }
]

All of the above headers are important.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "ok"
}
Request Headers:
 
  • Authorization – required OAuth token to authenticate the request
  • Content-Type – type of the request body (only JSON is currently supported)
Request JSON Object:
 
  • _timestamp (string) – A datetime representing the start of the period that the data refers to. Required.
  • _id (string) – A string that uniquely identifies that record. If a record with that identifier already exists, it will be overwritten. Optional.
Status Codes:
  • 200 OK – data from the request body was stored in the data set

Emptying a data set

PUT /data/(string: data_group)/(string: data_type)
Synopsis:Empty a data set by sending an empty array as a PUT request.

Example request:

PUT /data/carers-allowance/transaction-count HTTP/1.1
Host: www.performance.service.gov.uk
Authorization: Bearer abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz01
Content-Type: application/json

[]

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "carers_allowance_transaction_count now contains 0 records",
    "status": "ok"
}
Request Headers:
 
  • Authorization – required OAuth token to authenticate the request
Status Codes:
  • 200 OK – data set now contains no records

Client implementations

We provide several implementations of client code to talk to the Performance Platform: