1. Introduction
The OASIS REST API provides access to information about OASIS Projects via a RESTful API.
It is designed to provide programmatic access to OASIS Project information and its output is very similar to that of the existing "Export" function that can be found on the OASIS Projects list.
The base URL for the OASIS REST API is https://api.oasis.ac.uk/v1/
2. Authentication
To authenticate with the OASIS REST API, send an Authorization: Basic HTTP header with each request, containing a Base64 encoded email and password pair, separated by a semicolon. All API requests require authentication.
3. Projects Endpoint
You can request information about OASIS Projects using the https://api.oasis.ac.uk/v1/projects endpoint.
Specifying an OASIS Project ID e.g. https://api.oasis.ac.uk/v1/projects/oasis-project-123 will return information about that specific Project.
If you do not provide an OASIS Project ID then you must provide additional org_id and role parameters - the API will then return 10 projects per page by default, with the page number specified by the page parameter. You can instead, return anywhere from 1 to 1,000 projects per page by specifying the results_per_page parameter.
e.g. https://api.oasis.ac.uk/v1/projects?org_id=1000001&role=O1&page=1&results_per_page=20
Filtering Projects
You can provide the reviewer_id parameter to filter the results by reviewer ID.
You can filter the results by the date records were created and/or last updated by providing the
date_created_min, date_created_max,
date_last_updated_min and date_last_updated_max
parameters respectively, in YYYY-MM-DD format.
4. Other Endpoints
A list of your organisations and their respective IDs can be obtained by making a request to https://api.oasis.ac.uk/v1/organisations
A list of valid roles and reviewer IDs for an organisation can by obtained by making a request to
https://api.oasis.ac.uk/v1/reviewers/[organisation_id]
Roles are listed below.
Please note:
- Roles begin with the letter 'O' not the number '0'.
- Not every organisation has access to every role.
| Role | Description |
|---|---|
| O1 | Researcher which submits OASIS forms (commercial data inputter) |
| O1a | Community group which submits OASIS forms |
| O2 | Historic Environment Record (regional reviewer) |
| O2a | Other reviewing organisation |
| O3 | Museum/Archive |
| O4 | Organisation with responsibility for reviewing OASIS records nationally |
| O4a | Discovery and Excavation in Scotland |
| O5 | Organisation which needs to download completed OASIS records for analysis |
5. Code Example
Below is a (server-side) JavaScript code example using Fetch.
const email = 'your@email.ac.uk';
const password = 'yourPassword';
const encodedPair = Buffer.from(`${email}:${password}`).toString('base64');
fetch('https://api.oasis.ac.uk/v1/projects/oasis-project-123', {
headers: {
Authorization: `Basic ${encodedPair}`)
}
})
.then(res => res.json())
.then(json => console.log(json));