Getting started with the Surpass OAPI

The Surpass OAPI uses standard HTTP protocols to send and retrieve data. Requests can be made to each Surpass OAPI from a Surpass instance’s corresponding Swagger console, or any other HTTP client.

This article explains what makes up a request to and a response from the Surpass OAPI, and how to access your Surpass OAPI Swagger console.

What makes up a request?

A request to the Surpass OAPI is made up of header, query, or path parameters, along with properties in a request body if required, sent to an endpoint with a specified method.

The methods available for the Surpass OAPI are:

Requests can be sent from any HTTP client. However, authorisation details must also be passed in an authorization header parameter. Read Connecting to the Surpass OAPI for more information on authorising and authenticating requests to the Surpass OAPI.

The Surpass OAPI can accept data in JSON or XML format. You must specify the data type by sending a content-type header parameter with the value application/json or application/xml, and the data length using a content-length header parameter.

Sample request

Expand the following section for a sample request.

{
    "subject": {
        "reference": "Subject1"
    },
    "name": "Multiple Choice question",
    "status": "Live",
    "stemComponents": [
        {
            "contentType": "RichText",
            "content": "What is the capital city of Belgium?"
        }
    ],
    "mark": 1,
    "answerOptions": [
        {
            "correct": true,
            "answerColumns": [
                {
                    "contentType": "RichText",
                    "content": "Brussels"
                }
            ]
        },
                {
            "correct": false,
            "answerColumns": [
                {
                    "contentType": "RichText",
                    "content": "Brugge"
                }
            ]
        },
                        {
            "correct": false,
            "answerColumns": [
                {
                    "contentType": "RichText",
                    "content": "Antwerp"
                }
            ]
        }
    ]
}

What makes up a response?

A response from the Surpass OAPI contains a standard HTTP status code to indicate the success or failure of the request, header parameters, and a response body containing any relevant information.

If sent with authenticated authorisation details, the HTTP status code of a successful call is 200. An unsuccessful request may return a HTTP status code of 404, for example, and an ErrorCode property in the response body that indicates what the issue is.

A response body is always returned in the response to a successful request. In the case of successful GET requests, the requested information is returned in the response body.

For most POST, PUT, or DELETE requests, the response body simply details the unique identifier and/or unique reference code of the new or affected entity along with href and serverTimeZone properties.

The Surpass OAPI can return data in JSON or XML format. By default, JSON is returned. To return XML data, send an accept header parameter with the value application/xml.

Sample response

Expand the following section for a sample response.

{
    "response": 1,
    "serverTimeZone": "GMT Standard Time"
}

Surpass OAPI Swagger console

Each instance of Surpass has an OAPI Swagger console. To access it, add /oapi/index.html to your Surpass instance’s URL.

The Swagger console lets you test the Surpass OAPI by directly sending a HTTPS request to any of the available endpoints for your instance of Surpass. It automatically generates the endpoint URL, header parameters, and request body, leaving you to complete/amend any parameters and properties as needed.

For more information on the Surpass OAPI Swagger console, read Using the Surpass OAPI Swagger console.