Sessions Attendance Feed - API Spec

This is the development specification for an authenticated API endpoint that supplies Session (instance and attendance) data to a consumer based on a Project and date range.

This API is motivated by an interest in Upshot providing a feed to Org A, and other similar providers of services to a Delivery Organisation, where the Delivery Organisation is a mutual client of both.

This specification does not address any issues around data use agreements. For the purposes of this specification it is assumed that all data used in the API will have valid agreements in place between all parties to which the data relates.

Note: This specification doc is intended for a developer to access the feed and use the information produced. If you would like us to take the initial step of authenticating the API for your existing user profile, which will allow access to the feed, please contact support@upshot.org.uk

• Upshot API Framework
• Mapping data schemas
  • Required Attributes
  • Auditing Attributes
• API Endpoint
  • Request
  • Response
  • Error responses
• Browsable API

Upshot API Framework

Upshot has a RESTful API framework based on HTTPS requests to API endpoints that send and receive JSON payloads.

API endpoints can be public or private. Private endpoints require an Organisation user account within Upshot and for it to be authorised to access the API. Authentication is performed by sending a token in the request header (the token is obtained via an API endpoint).

The framework will support an increasing number of endpoints, developed as required to support new functionality.

This specification is designed around providing an endpoint which can be expanded to provide general support to consumers for managing Sessions within Upshot, e.g. GET, POST and PUT requests, and so attributes will be 'in the language of Upshot'. This specification focuses on support for a GET request of Sessions within a Project: the data mapping between Upshot and Org A is very close so it would be relatively straightforward to parse responses into the Org A schema on the consumer side.

Mapping data schemas

The Org A schema is summarised in this ERD:

There is close mapping to data within the Upshot schema. Limiting the detail shown, an equivalent ERD for Upshot is:

At a high level therefore there is the following broad mapping of attributes:

Required Attributes

In Upshot most attributes relating to Attendees are not required. An individual Delivery Organisation can largely configure what attributes are mandatory for them (as well as create their own custom attributes). The only Attendee attributes that are globally required are a first name and gender (of which 'Unknown' is an option). Attendees automatically have a primary key ID and a unique random identifier.

Therefore, depending on the Delivery Organisation's configuration Attendees might or might not have attributes for DOB, Postcode,Email, Disability and Ethnicity.

Similarly, when attending a Session the Facilitating /Delivery Organisation can configure what attributes of the attendance are required. The presence of an Attendee Session entity is an indicator of attendance.

Therefore, depending on the Delivery Organisation's configuration Attendee Sessions might or might not have attributes for PersonType, Duration and Fee.

Other attributes listed in the data mapping table above can be expected to have values.

Auditing Attributes

The datetime when a Session was processed is recorded.

The datetime it was last updated is recorded.

The datetime that an Attendee's Attendance was last updated is recorded. Although individually recorded this occurs in the same transaction when a register is saved. Therefore the datetime for one of them can be taken as representing the last time the register was saved, it will not identify whether an individual's Attendance attributes changed after an update(inspection of the API data attributes is necessary to determine that).

The last updated datetime of the Session is updated when the Session is processed and when its register is saved, as well as having core attributes updated which might not be exposed in the API data. A change in last update datetime does not necessarily mean any of its API data will have changed.

The datetime that an Attendee's attributes were last updated is recorded. This covers many attributes not exposed in the API data. Therefore it will not identify whether an individual's core Attendee attributes changed after an update (inspection of the API data attributes is necessary to determine that).

API Endpoint

Endpoint requests will be scoped to particular Delivery Organisations . In order to make a request there will need to be a user account within the Delivery Organisation with API access and a suitable role for viewing Sessions of the requested Project. This setup would be managed by the Service Provider (the Upshot support team).

Request

The consumer (Org A) would be supplied with the username and password of the user account. These credentials would be used to obtain the authentication token from the API (a one-off request, not covered here). This authentication token must be supplied in all requests to the endpoint.

Org A would also be supplied with the Project ID relating to the Sessions of interest and this would be used in the request.

Different Delivery Organisations would require different authentication tokens (because they are associated with different user accounts) but the process of request and response will be the same.

HTTPS GET requests will be made to an endpoint of the form:

/api/v0/projects/[ID]/sessions/attendance/

where [ID] is the Project ID.

Sessions can be scoped to a date range by supplying from and/or to GET parameters (using ISO8601dates):

/api/v0/project/[ID]/sessions/attendance/?from=2017-01-01&to=2017-04-30

An example of a full request using Curl (where 'abc' is the token):

curl -H "Authorization: Token abc"

--get--data from=2017-01-01 --data to=2017-04-30

https://app.upshot.org.uk/api/v0/projects/1/sessions/attendance/

Any client-side implementation able to make a HTTPS GET request can of course be used.

Response

Upon a successful request the API will return a HTTP 200status code and a JSON payload.

The high level structure of the payload will be:

●      Core attributes of:

○      Project

○      Project's Programme

○      Project's Delivery Organisation

○      Programme's Facilitating Organisation

●      List of Sessions; for each Session:

○      Core Session attributes

○      List of Attendances; for each Attendance:

■      Core Attendee attributes

●      At the time of request, not at the time of session attendance, so the same for all sessions

■      Core Attendance attributes

●      Session count

●      Truncation flag if the number of available sessions exceeded the maximum for one request (see later)

Sessions returned will be those scoped by the following criteria:

1.     Associated with the requested Project via Activity

2.    Within the date range specified by the from and to query parameters (inclusive),otherwise all those within the Project's start and end dates.

3.    Only 'Processed', non-abandoned Sessions.

a.     Non-processed Sessions are in draft form, therefore cannot be considered complete or accurate.

b.    For simplicity abandoned Sessions will not be included.These could be but would require a status attribute to be supplied (and utilised) for the Session in order to identify abandoned Sessions.

c.     NB: If a processed Session is abandoned but 'not counted' (as opposed to 'counted' it becomes unprocessed and would consequently no longer appear in the returned Sessions. This is a rare event ~0.2% of all Sessions in Upshot.

4.    Only 'Register'-type Sessions (those with individually identifiable Attendees). 'Headcount'-type Sessions will not be included.

5.    For performance and stability reasons a maximum of 100 sessions will be returned per request. As sessions are ordered by datetime the earliest sessions will be returned.

a.     There is a session_count attribute which is equal to the length of the sessions attribute list.

b.    If there were more sessions available than the maximum then the truncated attribute will be true, otherwise false.

c.     If truncated is true then the available sessions that weren't returned (or the next batch of 100) can be obtained by setting the from query parameter to the date of the last (latest) session in the sessions attribute list.

A sample of a JSON payload is:

{

'project':{

'id': XXX,

'name:'Project A',

'url':'https://app.upshot.org.uk/api/v0/projects/1/',

'start_date':'2016-05-01',

'end_date':'2017-09-30'

},

'programme':{

'id': XXX,

'name: 'Programme A'

},

'delivery_organisation':{

'id': XXXX,

'name: 'Org A'

},

'facilitating_organisation':{

'id': 2361,

'name: 'FO A'

},

'session_count':10,

'truncated':false,

'sessions': [

{

'id': XXXX,

'title': 'XXXX Home',

'datetime':'2017-02-07T14:00:00+00:00',

'duration_mins': 60,

'processed_on': '2017-03-13T15:43:23+00:00',

'session_last_updated': '2017-03-13T15:46:00+00:00',

'register_last_updated': '2017-03-13T15:46:00+00:00',

'activity': {

'id': XXXX,

'name': 'Art classes',

'activity_type': 'An example',

'activity_type_id': XXXX,

'activity_type_family:'Non-sport personal development',

'activity_type_family_id:0

},

'location': {

'id': XXXX,

'name': 'Location A',

'line_1': 'High St',

'line_2': '',

'line_3': '',

'town': 'Winslow',

'county': 'Buckingham',

'postcode': 'XXXXX',

'longitude': '-0.8824',

'latitude': '61.9460',

'active_places_id': null

},

'attendees': [

{

'id': XXXXX,

'public_identifier':'d5a76887ae90463a',

'attendee_last_updated': '2017-03-13T15:43:12+00:00',

'first_name':'Jane',

'last_name': 'Doe,

'age': 78,

'email': 'jane.doe@foo.com',

'gender': 'Female',

'disability': true,

'ethnicity': 'White English',

'ethnicity_id': 1,

'postcode': 'XXXXX',

'attendee_type': 'Participant',

'attendee_type_id': 0,

'attendance_fraction': 0.75,

'amount_paid': null

},

...

]

},

...

]

}

Error Responses

Invalid requests return a non-200 status code and a JSON response describing why the request was invalid.

Authentication token not supplied:

401 status code

{"detail":"Authentication credentials were not provided."}

Authentication token supplied but not correct:

401 status code

{"detail": "Invalid token."}

Requesting a project that the user associated with the token does not have access to:

403 status code

{"detail": "You do not have permission to perform this action."}

Invalid query parameter:

404 status code

{"detail": "Invalid 'from' parameter"}

Internal application exception:

500 status code

{'error': '500:An error occurred and will be investigated'}

All the errors responses other than those with a 500 status code can be resolved from the client side (assuming API access has been granted in the first place). Requests receiving a 500 status code should not be repeated without an exponential back off strategy. We are notified of 500 errors and will address them as soon as possible.

Browsable API

A browsable API is available which documents the available endpoints. You wouldn’t use the browsable API for actual API integration but it’s a useful tool during development.

To access it in your browser go to:

https://app.upshot.org.uk/accounts/login/?next=/api/v0/

And log in using your account credentials.