The Surpass OAPI has been created to improve the way you automate interaction with Surpass. It supports some features of the API v2 as well as some additional functionality. The OAPI significantly improves the performance of the Surpass API and is built on the latest .Net Core technologies and adopts the OpenAPI specification (https://www.openapis.org/about).
Note: The Surpass OAPI is new and still under development, therefore the resources currently available are limited. To start using the OAPI, please contact your BTL Account Manager.
Integrating with the Surpass OAPI offers many benefits, including:
- Improved performance
- Automatically generated documentation using
- More control and flexibility with queries
Some features exclusive to the OAPI include the ability to
specifically POST multiple choice, multiple response and either/or question
types, tag collections, item set positioning and the bulk posting of tag groups
against an item. The 'Item Search' and 'Item Lists' tabs within 'Item Authoring' are also supported by the Surpass OAPI.
Before utilising the Surpass OAPI and beginning to integrate your organization’s systems with Surpass, it is beneficial to understand the way Surpass works and how the entities all relate to one another.
These core entities are:
Centres – A centre refers to the place where a test is taken, e.g. a school or college. A centre needs to be available before any subjects, users or candidates can be created, as these all need to be associated with a centre.
Subjects – A subject is where multiple users collaborate in order to create the questions and content to compile a test in Surpass. Subjects are shared with centres and permissions can be defined to allow users to work on the subject.
Users – A user is a person who interacts with Surpass day to day. Users vary from site administrators to question authors to invigilators. Permissions can be assigned at a site, centre and subject level, and the users’ role is determined by what permissions are granted to them.
Candidates – Candidates are the students or learners that take tests within the system and only see the Surpass delivery engine in the end-to-end test delivery process. Candidates should be associated with the centres and subjects which are relevant to them. They will only be eligible to take tests under associated subjects and at associated centres.
Further information on the basics of Surpass can be found in the ‘Before you begin’ section of the Surpass Knowledge Base.
Below is a list of the resources and methods that are available within the Surpass OAPI:
|GET||Allows user to check existing analytics records in Surpass and to return attributes for multiple candidate keycodes.
|GET||Allows you to check existing item records in Surpass and to return all attributes for an individual item record.|
|DELETE||Allows user to delete existing item records in Surpass.|
|POST||Create items in Surpass using this method.|
|PUT||Update tag values and enemy relationships in Surpass using this method.|
|POST||Create item sets using the Surpass OAPI.|
|PUT||Update item sets in Surpass using this method. The name and what specific items are in the set can be updated.|
|POST||Allows user to create tag collections in
|GET||Allows user to check existing tag collection records in Surpass and to return all attributes for an individual tag collection.
|PUT||Update tag collections in Surpass using this method. The name and specific tag values/subcollections in the collection can be updated.|
|DELETE||Allows user to delete tag collections in Surpass.|
|POST||Allows user to create tag collection groups in
|GET||Allows user to check existing tag collection group records in Surpass and to return all attributes for an individual tag collection group.|
|DELETE||Allows user to delete tag collection groups in Surpass.|