API Documentation

Technical documentation for our Platform API

Resources


User Guide

Introduction

The Assembly API is built around the REST and a collection of open standards/protocols in order to comply with as many consumers as possible. We recommend that developers wishing to work with our APIs are familar with the following technologies before continuing:

  • HTTP / REST All communication is handled over HTTPS using standard HTTP verbs, status codes and headers.
  • JSON All response bodies are returned in JSON format.
  • OAuth Authorisation is handled via OAuth 2.0.
  • Bearer Tokens Resource Authentication is managed with Bearer Tokens.

Endpoints

All live API calls should be made over HTTPS to:

https://api.assembly.education

All Sandbox API calls should be made over HTTPS to:

https://api-sandbox.assembly.education

All live OAuth flow requests should be made to:

https://platform.assembly.education

All Sandbox OAuth flow requests should be made to:

https://platform-sandbox.assembly.education

Versioning

The API requires that you specify the version of the api that you which to consume in the Accept request header. The current version of the API is version 1.

curl -H "Accept: application/vnd.assembly+json; version=1"

Failure to provide a valid version will result in a 406 response.

Status 406
{"error": "unsupported_version"}

Within a given API version additional features and functionality (including new: endpoints, attributes, headers or optional parameters) may be added without warning but backwards compatibility will be maintained.

Authentication

Assembly rely on OAuth to manage access to school data and Bearer Tokens to authorise API requests. The platform can issue two types of tokens to an application, app level tokens and school level tokens.

Tokens give access to data within the Assembly Platform. It is therefore vitally important that they are treated as highly confidential and handled / stored accordingly. Any suspected breach of a token's security should be reported to Assembly immediately.

App Level Tokens

These can be generated at any time through the Assembly Platform website, they never expire and give access to application level resources. At the time of writing these tokens are of limited value.

School Level Tokens

These can only be acquired by a school explicitly authorising your Application to access their data via an OAuth flow. School level access tokens have a scope and expiry time associated with them.

When requesting access to a school you must request the scopes of data that your application requires access to. The available scopes are:

Scope Description
school School level information that is generally publicly available or non-sensitive. Examples include the school's name, URN, academic years, subjects, year group names/codes and registration group names/codes.
calendar Calendar events from the school's MIS calendar, as well as details of term dates (currently available on SIMS only).
students Personally identifiable student information such as name, UPN, date of birth, year group and registration group.
student_demographics Contextual student information such as gender, ethnicity, pupil premium, prior attainment and SEN category.
student_care The 'looked after' status of the student.
student_addresses The student's home address and postcode.
contacts Student contact (e.g. parent/guardian) details.
staff_members Personally identifiable information for staff members (teachers) such as their name, position and email address.
teaching_groups Teaching Group names, subjects and the student / supervisor lists (what Teaching Groups are available is governed by the Subject Mappings the school have configured).
attendances AM/PM roll call attendance marks for students.
assessments.national National assessment data stored on the MIS. For example, Key Stage 2 SATs results.

Optional and Required Scopes

Scopes can be defined as either required or optional. To comply with data protection regulations and good practice, all scopes that are not necessary for the core purpose of an app should be defined as optional.

If a scope is defined as required, it will be listed on a school's Data Access Request, and the school must agree to sharing this scope of data in order to authorise an app. Scopes can be defined as required by including :required after the scope in an authorisation request (for example: students:required).

If a scope is defined as optional, it will be listed on a school's Data Access Request with a check box next to it, which is by default not ticked. A school can then opt in to these scopes when authorising an app by ticking the relevant boxes. Scopes can be defined as optional by including :optional after the scope in an authorisation request (for example: student_demographics:optional).

Please note: if :required or :optional is not specified after the scope name, scopes behave as if they are required.

Scope Dependencies

Some scopes of data have dependencies on others. The student_demographics, student_addresses and contacts scopes are all dependent on the students scope. Therefore, requesting one of these in your access_token will also return the students scope.

The student_care scope is also dependent on the student_demographics scope.

Token Expiry & Refresh

School level Access Tokens are currently valid for 30 days although your application should not rely on this as token expiry times are likely be reduced in future.

Each successful OAuth authorization also contains a refresh_token, Refresh Tokens should be used to aquire a new access token upon expiry.

Using Tokens

All API endpoints require Bearer token authentication. The token should be set in an Authorization request header.

curl -H "Authorization: Bearer b2s7a9s8BQokikJOvBiI2HlWgH4olfQ2"

API requests that are missing an Authorization header will receive a 401 response:

Status 401
{
  "error": "invalid_request",
  "message": "an access_token is required."
}

Read More in the OAuth documentation…

Conditional Requests

Some of the API endpoint responses contain a Last-Modified header. You can use this value to make subsequent requests to these endpoints using the If-Modified-Since header; the server will then return only data which has changed since this date. If no data has changed since this date, then the server will return a response of 304 Not Modified .

Note if a 'full sync' has been performed on a school then all data will be flagged as having changed, which means that using this header will result in all data being returned.

The following endpoints currently support conditional requests:

  • Students
  • Staff members
  • Calendar events
  • Teaching groups
  • Registration groups
  • Year groups

Errors

Assembly uses HTTP response status codes to indicate the status of an API request.

  • Status codes in the 200 range indicate a successful request.
  • Status codes in the 400 range indicate that the request has failed, usually due to a client error.
  • Status codes in the 500 range indicate that the request has failed due to a server error.

Generally error responses contain a JSON body made up of an error key and a more descriptive message hover this is not guaranteed. For example:

Status 401
{
  "error": "invalid_request",
  "message": "an access_token is required."
}

Rate Limiting

In order to protect the availability and security of our systems all HTTP calls are subject to rate limiting. Except where noted the following limits are in place.

In extreme circumstances very abusive clients may be subject to blacklisting.

Please note: We are evaluating these limits and they are subject to change. If you feel you require a higher limit please contact support.

Each Access Token is limited to 600 requests within a 5 minute window, or two requests per second. If you exceed this limit you will receive a response that tells you:

  • count the number of requests you have made with the current token.
  • period the number of seconds until the current token may make another request.
  • limit the total number of requests the current token may make within a 5 minute window.
The response will look something like this:
Status 429
{
  "error":"too many requests",
  "data": {
    "count": 601,
    "period": 300,
    "limit": 600
  }
}

Pagination

Any request that results in a list type being returned is presented as a paged response. The response data gives you the information to navigate through the paged data set. Further pages can be requested using the page querystring parameter.

Status 200
{
  "object": "list",
  "total_count": 10,
  "total_pages": 2,
  "current_page": 1,
  "prev_page": null,
  "next_page": 2,
  "data": [ 1, 2, 3, 4, 5 ]
}

Data Model

Full field level documentation on our data model can be found here.