The SwiftAssess API enables programmatic access to objects stored on SwiftAssess's servers, including programs, questions, users, grades, exams and payment information. Clients are encouraged to use this API to enhance and extend the SwiftAssess user experience and provide adapters into their existing applications and platforms.

 

 

Technical Overview

 

The SwiftAssess API is a REST API that accepts HTTP/HTTPS requests. By default, it returns data formatted in Javascript Object Notation (JSON) unless XML was specified in the request body. Other response formats may be supported in future releases.

 

All methods require an API Access Token, which requires registering for an account with SwiftAssess.

Note: API keys might change from one version to another.

 

 

Structure of the API Methods

 

The SwiftAssess API consists of a number of methods grouped into categories according to their function. The method calls that comprise the SwiftAssess API are designed to enable stateless operations on server-side objects. Objects within the system, such as a User or Program, can be uniquely identified through URLs. For example, the format of URLs for accessing Users using the Users/{username} method is http://api.swiftassess.com/users/{username}, where {username} represents a unique user in the system.

 

In some cases, commands can be placed after object IDs to obtain information specific to that object. The Group method supports two such commands: assessments and users. For example, a group with an ID of 10298394 returns a list of all users associated with that group by using the Groups/{groupId}/users method using the command http://api.swiftassess.com/groups/10298394/users.

 

 

Obtaining an Access Token

 

You must swap your API Key & Secret with an access token in order to be able to access the API methods. This is done by issuing an HTTP POST request to the SwiftAssess API token endpoint http://api.swiftassess.com/api/auth/token.

The required POST parameters are:

•app_key (Your unique account key as assigned by SwiftAssess)

•app_secret (your account secret as assigned by SwiftAssess)

•grant_type=access_token
* You can find your key & secret in your SwiftAssess account under Account Settings > API.

 

An unencrypted POST request might look like this:

 

 

The server will return a refresh token and an access token in a JSON object which is valid for a specific time period:

 

 

 

Refreshing an Access Token

 

When your access token expires, any SwiftAssess API method your application calls will respond with a HTTP 401 error status. At any time, you can use the token endpoint with your refresh token, api credentials, and the HTTP POST parameter grant_type=refresh_token to obtain a new access token:

 

 

 

Using the Access Token to Call API Methods

 

You can use your access token to call a protected API by including it in an access_token query parameter or the HTTP Authorization header. For example, you can use the curl command-line application to call the Users API with your access token as follows:

 

curl http://api.swiftassess.com/Users/full?access_token=4eb1de8bf06b10210e000005

 

 

JSON Response Format and Error Codes

 

Valid API responses are returned by default in the JSON format, which is documented extensively at JSON.org. JSON can be parsed in a JavaScript application using either the ECMAScript standard JSON.parse() method, or the JavaScript eval() function. Other languages such as PHP also define APIs for parsing JSON code.

A successful API response resembles the following format (this example is taken from the questions/5522143/ method):

 

   { "Question": { "title": "What does H2O stand for?" }

 

 

The Question property is a object that defines the list of response properties returned by the method, along with their associated values. These properties may be scalar values, zero-based arrays, associative arrays, or objects.

 

An error is returned as a JSON response inside of an HTTP error response with a response code of 400 or greater. Note that a single invalid call can return an array of two or more specific error codes. The following JSON example response demonstrates the error generated when an application attempts to call the groups/{groupId}/users method without a valid groupId parameter. The individual response properties are described below.

 

 

 

 

Calling an API method that is not defined by SwiftAssess will result in a standard 404 File Not Found HTTP response. The server may also return a 503 Server Unavailable response in those rare cases where the SwiftAssess server is overwhelmed by requests, or has been taken down for regular maintenance.

 

Specific methods in the SwiftAssess Developer API can return error codes specific to those methods; these are documented in the individual documentation pages for each method. A list of general errors that can be returned by multiple APIs is given on the Common API Error Codes page.

 

SwiftAssess © 2021