The Surpass API offers the ability to submit a GET request to return all attributes for an individual basic page, create basic pages via the POST method and update existing basic pages by calling the PUT method.
Below we have listed the operations, http verbs and an example URL for the BasicPage resource within the Surpass API.
|Operation||HTTP Verb||Example URL|
|Read (Individual by ID)||GET||https://...surpass.com/api/v2/BasicPage/359377|
Within the table below we have provided all of the attributes included in the BasicPage resource. This includes the attribute name, data type, if the attribute is a unique identifer and if the attribute is mandatory when sending a POST request.
|Attribute Name||Type||Notes||Unique Identifier||Mandatory for Create (POST)|
|id||int||Unable to POST/PUT||X||N/A|
|type||enum, string||Will define if this is an Introduction, Information or Finish page.||X|
|subject||Resource||ID or Ref can be supplied.||X|
|htmlText||string||Allows for HTML formatting|
|mathMl||string||Determines whether the main text box is rendered in MathML.|
|contentType||string||"RichText" for example|
|additionalHTMLText||string||Allows for HTML formatting. This text will appear in the additional information box.|
|additionalMathMl||string||Enables the additional information box to be formatted in MathML.|
|folder||Resource||ID and Position can be supplied.|
|status||enum, string||Can be "Draft", "To Review", "Reviewed", "Live" and "Withdrawn".|
|comment||string||Adds a new comment to the item.|
|mediaItems||object||ID should be supplied. Only one media item accepted.|
|sourceMaterials||object||ID should be supplied.|
|stemComponents||collection||A collection of text, images or equations that make up the question text. These will be added directly after one another rather than inline. This property is expected to be used rather than questionText. Only text, media or MathML can be supplied in each object, media is not allowed in the first object to follow UI validation.|
|stemComponents / text||HTML||Text included in the question stem. Formatting can be applied using HTML.|
|stemComponents / mathMl||MathML||Formula can be added to the question stem using this property or returned if this was authored in the user interface. It must be passed in using valid MathML.|
|stemComponents / media||resource||Any media embedded into the question stem.|
|stemComponents / media / id||int||The id of the media embedded into the question stem. This id relates to the media resource.|
|allowOpenImageInPopup||boolean||If the item contains an image, this option will allow the image to be opened in a popup window.|
|mediaLayout||string||"AutoSelect", "LeftTitle", "RightTitle".|
|assistiveMedia||object||This object refers to assistive media that can be assigned to page text to help provide an alternative method of providing the question text to the candidate e.g. in audio format.|
|tools||object||This object refers to Tools that can be associated with a page to help a candidate familiarise themselves before working their way through the test. At current, only a calculator can be used, and choose from 'basic' or 'scientific' to enter in the 'Settings' field.|
|owner||id||The user who owns the particular item.|
- ID is the unique identifier for this resource in the Database.
GET Request and Return
The GET BasicPage resource can be called directly by browsing to the URL, any required parameters such as $filter, $orderBy, $skip and $top would need to form part of the URL that is sent. Below we have provided examples of JSON and XML responses that would be returned from the Surpass API when requesting the GET method for the BasicPage resource. It is important to remember that the return information will be included within the response object that forms part of the standard GET response; this is detailed in the page understanding the Surpass API.
Example GET request and response (JSON)
Example GET request and response (XML)
POST Request and Return
The POST BasicPage method requires the attributes listed above to be submitted as part of the body of the HTTPS request. This can be submitted in either JSON or XML format, the content-type used will need to be submitted as part of the header of the request. An example of the address, header and body of the request (for both formats) can be found below.
Example POST request and response (JSON)
Example POST request and response (XML)
PUT Request and Return
PUT Requests should reference the ID within the resource. The resource being updated should be included in the body of the request and can be sent in either JSON or XML format. Only the field you want to be updated needs to be included within the request all others can be omitted; these fields will retain their current values. The content-length, content-type and Authorization will also be required in the header of the request. All attributes included in the body of the PUT request are optional if an attribute is omitted it will retain its current value set in the DB.
Example PUT request and response (JSON)
Example PUT request and response (XML)
To successfully call the BasicPage methods, the user specified in the header of the request must have the "Item Writer", "Item Reviewer" or "Item Publisher" role for the subject specified. The item status that is being set in the request must correspond to the user’s permission.