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:

Go
Java implementation intended to periodically poll a JDBC data store and push data Performance Platform
JavaScript
Python

Glossary¶

Aggregate: Applying a function to a Measure, such as summing, calculating the mean etc
Backdrop: An application that is part of the performance platform. It provides the read and write API for data.
Chart: A graphical representation of a Measure and a Dimension (eg number of applications by channel)
Dashboard: A page showing multiple metrics, typically for a single service
Dataset: A collection of data of a particular type. In relational terms, this is a table. In non-relational terms, this is a collection of documents.
Data type: Each Dataset stores a particular type of data, eg current traffic volume
Dimension: A non-numeric type of :term: Field eg an operating system or browser
Element: A component of a Visualisation such as a chart or aggregate summary
Field: A ‘column’ in a dataset
Measure: A numeric type of :term: Field, eg number of applications. A Measure may be aggregated
Metric: A specific data series, eg completion rate, user satisfaction, page load time, uptime etc
Module: A module is a metric and a visualisation together, eg digital take-up shown as a line chart
Observation: A ‘row’ in a dataset
Service: A transactional service is a facility that enables users to exchange informsation, money, permissions, goods etc with government. For example: Renew you car tax, Apply for Carer’s Allowance, Apply for a fishing rod licence etc.
Service Group: A group of closely related services, eg Carer’s Allowance service group includes applications, existing claims, appeals etc
Spotlight: An application that is part of the performance platform. It is responsible for rendering data from the Backdrop API to display visualisations of service performance
Stageprompt: A JavaScript library that provides an adapter over analytics software
Transaction: An exchange of information, money, permissions, goods etc that takes place between government and users (individuals, businesses and other organisations). Examples include an application for a passport, a renewal of a patent, an update to the Organ Donation Register. A transaction will usually result in a new (or amended) government record.
Visualisation: A set of Elements using the Measures and Dimensions from the Dataset

Get a Performance Platform dashboard¶

This page explains how to get a dashboard on the Performance Platform.

A published dashboard is a requirement of the Digital by Default Service Standard, which all transforming services must meet. All services, whether transforming or not, need to provide data on transaction volumes every quarter.

Before you start¶

Please discuss your dashboard requirements with whoever will be signing off the publication of the dashboard as soon as possible.

How to get a dashboard¶

A standard dashboard for transactional services includes four mandatory KPIs.

Cost per transaction (the average cost to the government of each completed transaction)
User satisfaction (how satisfied users feel after completing a transaction online)
Completion rate (the percentage of users who complete a digital transaction once they have started it)
Digital take-up (percentage of all transactions which are completed using digital channels)

How to get a transactional services dashboard¶

To get a dashboard, email the following information to performance@digital.cabinet-office.gov.uk. You can use the same address for further enquiries about dashboards and the Performance Platform.

Your contact details	Your name Your email address Your phone number
Service description	The name of your service Short description of what the service does and who its intended users are URL of the service start page (and the start page on GOV.UK if this is different)

We’ll need access to the following data in a format that can be read by our database. Please send details of the data, but do not put the data itself in an email.

Digital take-up	Send a completed copy of the transactions by channel spreadsheet
Cost per transaction	We will take your costs data from the transactions data collection run every quarter by GDS. All services included in this exercise are listed on the Performance Platform’s services page. If your service isn’t listed, email Clifford Sheppard. If your service doesn’t have cost information, here’s how to calculate it .
User satisfaction	URL for your GOV.UK ‘done’ page. You can get a ‘done’ page by clicking ‘content change’ on the GOV.UK support site. If you can’t access this, please speak to the GDS point of contact in your department. If you capture user satisfaction in a different way please tell us and we’ll try to include it.
Completion rate	If you use Google Analytics we need: View and read permissions for googleapi@digital.cabinet-office.gov.uk Details of at least one goal that allows us to calculate the completion rate Your View ID Let us know if you use a different analytics provider (e.g. Webtrends, Piwik). Name and email address of people who will upload the data on an ongoing basis We can also use the digital take-up data to show transactions by channel.

If you would prefer to use our platform API to automate the upload of any data please let us know.

Once we have this information we can publish your dashboard to a non-linked, non-searchable URL.

When the dashboard is complete and signed-off, it will be made publicly available.

Keeping your dashboard up to date¶

You own the data in the dashboard and are responsible for maintaining its quality.

If your dashboard is supported by an API then this data will update automatically.

If your dashboard is supported by spreadsheet data you’ll need to regularly upload current data which will then automatically display in the dashboard. You do this using a GOV.UK Sign on account, which we can create/update for you.