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 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.


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 Allows user to check existing analytics records in Surpass and to return attributes for multiple candidate keycodes.
Item
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. 
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.
TagCollection
POST Allows user to create tag collections in Surpass.     
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.
TagCollectionGroup
POST Allows user to create tag collection groups in Surpass.
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.

Feedback and Knowledge Base