University Student API¶
This page gives an overview of the University Student API, describing its current status, where and how it's developed and deployed, and who is responsible for maintaining it.
Service Description¶
The University Student API is a read-only REST API which allows access to identity information related to students at the University. It exposes an easy-to-consume interface, allowing clients to query students by student number (USN) or by affiliation (institution or academic plan). The API exposes a view of data from the University's Student Management System (CamSIS).
The University Student API queries data from CamSIS using an HTTP endpoint which exposes a stream of student entities in XML form, and caches data within GCP buckets to allow for effective querying by affiliation.
Service Status¶
The University Student API is currently alpha and not under active development. New use-cases
and improvements for the service need to be well-understood and scoped alongside the considerations
below.
The API was initially developed as a means to allow the new University Card System to query data from CamSIS, with a view to provide an API which can be re-used by other client applications. Going forward, it would be preferable for such APIs to be developed and maintained as part of CamSIS itself rather than as separate services outside of CamSIS. Therefore, before significant improvements / changes are made to the University Student API, the ability to expose this information directly from CamSIS should be assessed.
Contact¶
Technical queries and support should be directed to uis-devops-division@lists.cam.ac.uk and will be picked up by a member of the team working on the service. To ensure that you receive a response, always direct requests to uis-devops-division@lists.cam.ac.uk rather than reaching out to team members directly.
Issues discovered in the service or new feature requests should be opened as GitLab issues in the application repository.
Environments¶
The University Student API is currently deployed behind the API Gateway:
| Name | URL |
|---|---|
| Production | https://api.apps.cam.ac.uk/university-student |
| Staging | https://api.apps.cam.ac.uk/university-student-staging |
| Development | https://api.apps.cam.ac.uk/university-student-devel |
The OpenAPI documentation for the production environment can be found on the API Gateway's developer portal.
Source code¶
The source code for the University Student API is spread over the following repositories:
| Repository | Description |
|---|---|
| API project | The source code for the API project |
| Infrastructure Deployment | The Terraform infrastructure code for deploying the API to GCP, part of the identity platform deployment |
Technologies used¶
The following gives an overview of the technologies the University Student API is built on:
| Language | Framework(s) |
|---|---|
| Python 3.9 | FastAPI |
Operational documentation¶
The following gives an overview of how the University Student API is deployed and maintained.
How and where the University Student API is deployed¶
The API is deployed to GCP Cloud Run as part of the Identity Platform Deployment project.
Secrets for each environment are held within
1Password
and bootstrapped using the
root-bootstrap sub-project of the identity deployment project.
Deploying a new release¶
A new release to staging and production can be triggered by running the pipeline of the default branch within GitLab.
Deployments to staging and development can be triggered manually by triggering a pipeline within the deploy identity project with the following variables set:
DEPLOY_ENABLED=<development|staging>
STUDENT_IDENTITY_DOCKER_IMAGE=<gitlab registry url of image to deploy>
Monitoring¶
The University Student API makes use of our GCP site monitoring module for monitoring of the production environment. This will send an alert to devops-alarms@uis.cam.ac.uk if any of the deployments have non-transient uptime check failures.
Additionally, an alert is configured to fire if the API has been unable to refresh its cache of data from CamSIS within the expected timeframe.
Alerting policies and their status can be viewed within the GCP Identity Meta project.
Debugging¶
The API's README includes information about running the service locally for debugging. Additionally, logs for the production instance can be viewed through GCP's Cloud Run console.
Operational issues with CamSIS¶
The University Student API relies on a feed of data from CamSIS, and therefore it's uptime is dependent on the uptime of CamSIS. Unexpected failure to query CamSIS should be raised with the CamSIS team using camsishelp@admin.cam.ac.uk.
Service Management and tech lead¶
The service owner for the University Student API is currently vacant.
The service manager for the University Student API is Dr Я Charles.
The tech lead for the Card Management System is av603.