Surpass OAPI > OAPI Basics > Using the Surpass OAPI Swagger console

Using the Surpass OAPI Swagger console

The Surpass OAPI adopts the OpenAPI (previously Swagger) specification, an open-source API standard used to describe API files. A working, testable API console can be generated from a Swagger specification. For more information about OpenAPI, visit https://www.openapis.org/about.

The Surpass OAPI Swagger console therefore 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.

This article explains how to send a request using the Surpass OAPI Swagger console.

TIP: The Swagger console provides an easy way to test the Surpass OAPIs against your instance of Surpass before setting up any integrations. As such, any requests made using the test console affects and returns real data from your instance.

We recommend creating a dedicated integration user that can be used when calling the Surpass OAPI. This is a good idea even if you are only testing the OAPI as it enables you to work in the Surpass UI and OAPI simultaneously without being logged out of the UI after each request to the OAPI.

In this section

1. Navigate to your Swagger console

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

EXAMPLE: https://{your Surpass instance}.surpass.com/oapi/index.html

2. Enter authorisation details

Select Authorize to open the Available authorizations dialog to authorise your requests using either basic or JWT authentication. For more information on authentication and authorisation, read Connecting to the Surpass OAPI.

3. Choose an API

All of the available Surpass OAPI resources and their methods are listed on the Swagger console page.

Expand the OAPI resource you wish to test.

The expanded section displays the available parameters, responses, and a request body where applicable.

Select Try it out to enable the parameters for editing.

4. Input path and query parameters

NOTE: Path and query parameters may not be required, such as for calls using the POST method where the identification of an object or resource is not required.

Any path or query parameters are listed in the Parameters tab.

Mandatory path parameters are indicated with a * required flag.

NOTE: The orderBy query parameter cannot be used in a request made to an OAPI endpoint using the Surpass OAPI Swagger console. Instead, a request must be sent to the endpoint from another source using the following format: ?orderBy=fieldName={fieldName}&ascending={operator}

5. Input request body

NOTE: A request body may not be required, such as for calls using the GET method.

Request bodies are pre-populated with all the available properties for the specified API. In the Item structure section of Request body, amend the properties and their values as required.

For information on the optional and mandatory request body properties of each OAPI, read the OAPI Reference documentation.

Changing the request body sample content type

You can change the format of the request body sample. This will automatically update the content-type header parameter.

Viewing the request body schema

Before selecting Try it out, you can view the request body’s schema.

6. Send request

Press Execute to send the request.

7. Read response

The response details its HTTP Code (A successful request returns a 200 code) and the returned Response body, Response headers, and Request duration, alongside a response code.

A Curl of the request and the Request URL endpoint was sent to is detailed firstly.

The Code column details the HTTP status code.

The Response body is returned. Select the clipboard icon to copy it or press Download to download a JSON file of the response.

Returned Response headers can be found in the next section.

The time it took to send the request is detailed in milliseconds in the Request duration section.

All the available responses, including possible error codes, are detailed at the bottom of the section complete with sample (Example Value) and Schema where applicable.

NOTE: You do not need to send a request to view the possible responses.

Once executed, you can clear the response using Clear.