Open the article in a separate window
The REST API allows access to, and manipulation of all data held within the Timetabling Solutions dataset. Access is defined through a combination of application and user credentials each of which has access to specific data and is combined reductively to decide the effective permissions of the application and user combination.
Documentation
The RESTful API and its documentation can be found at https://coreservices.timetabling.education. Navigating this URL in a browser will open developer documentation information about the API listing all calls, requests and response information.
Authentication
Authentication with the API can be done using the standard Basic scheme, a valid session is also required to make calls to the API.
Each call to the service must have an Authorization header that defines the context that the request is being made in. This is done to slow down or prevent bad actors from sending requests to the API.
There are two types of Authorization header, one that is used pre-authentication, which will use the app identifier and secret you have in your username and password fields, and one that is post-authentication which uses the authentication identifier (obtained as a response to authenticating) and the app secret.
The authenticate request should use the pre-authentication header, the username and password fields are for the credentials of a user account on the system. Each session is a combination of an app and user, the effective permissions for the session are those that overlap between the app and user, this means that a user won’t have their permissions elevated by logging into an app with higher privileges.
The response to the authenticate request will provide you with a response that indicates the outcome of the attempt, only “Success” indicates the user was successfully authenticated. After this, you can use the authenticationIdentifier in the response to construct the post-authentication Authorization header for other calls which require a session.
The Authorization header should contain a standard HTTP basic authentication value, this document from the W3C has a definition of the basic authentication scheme but essentially you must concatenate the username and password with a colon between them, base64 encode this and append to the text “BASIC “. Below is a pseudo code example:
Authorization = “BASIC “ + base64(“username” + “:” + “password”)
When you’re creating the Authorization header use the values defined above for pre and post scenarios in place of the username and password.
Initialising a Session
In order to make stateful requests to the API the client must first initialise a session by making a request to the https://coreservices.timetabling.education/api/Authentication/Authenticate endpoint.
This call requires the basic authorisation token to be made up of the Application Identifier and the Application Shared Secret.
e.g. [ApplicationIdentifier]:[ApplicationSharedSecret]
Subsequent Calls
Once a session has been instantiated calls should be made to other endpoints using the Authentication Identifier in place of the Application Identifier in the basic authentication token.
e.g. [AuthenticationIdentifier]:[ApplicationSharedSecret]
