Introduction to the Surpass OAPI

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 Swagger Tools
  • More control and flexibility with queries

Some features exclusive to the OAPI include the ability to specifically POST multiple choice, multiple response, either/or and essay question types; create and manage tag collections; alter item positions in item sets; and POST tag groups against an item in bulk. The 'Item Search' and 'Item Lists' tabs within 'Item Authoring' are also supported by the Surpass OAPI.


Surpass Model

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:

Method Description
AnalyticsResult
GET Check existing analytics records in Surpass and return attributes for multiple candidate keycodes.
Item
GET Check existing item records in Surpass and return all attributes for an individual item record. You can also retrieve individual versions of items.
DELETE Delete existing item records in Surpass.
POST Create items in Surpass using this method. You can also specifically create multiple choice, multiple response, either/or and essay question types.
PUT (Essay questions)
Update existing essay questions in Surpass.
ItemMetadata
PUT Update tag values and enemy relationships in Surpass using this method.
ItemSet
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.
Settings
GET Retrieve OAPI authentication settings.
PUT Update OAPI authentication settings.
TagCollection
POST Create tag collections in Surpass.     
GET 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 Delete tag collections in Surpass.
TagCollectionGroup
POST Create tag collection groups in Surpass.
GET Check existing tag collection group records in Surpass and return all attributes for an individual tag collection group.
DELETE Delete tag collection groups in Surpass.
TagGroup
POST Create tag groups in Surpass.
GET Check existing tag group records in Surpass and return all attributes for an individual tag group.
PUT Update tag groups in Surpass using this method. The name and specifc tag values in teh tag group can be updated.
DELETE Delete tag collection groups in Surpass.

Feedback and Knowledge Base