SelfHosted Adaptive v1.0.0

Download specification (OpenAPI).

This specification defines how to implement a self-hosted adaptive algorithm, so that you can define your own rules for selecting which Items to serve during an adaptive test via Items API.

Your self-hosted adaptive logic will need to be encapsulated in a web service secured by OAuth 2 and hosted at a public URL you define. Your service will need to implement a number of endpoints which Learnosity will call during the course of your self-hosted adaptive tests.

For example, if your service is hosted with a base URL of https://adaptive.example.com/v1/adaptive, you would need to pass the following in your initialization options to Items API.

{
  "security": ...,
  "request": {
    /* Usual Items API init options */
    "user_id": ...,
    "activity_id": ...,
    "session_id": ...,
    ...

    "adaptive": {
      "type": "selfhosted"
      "engine_url": "https://adaptive.example.com/v1/adaptive",

      "custom_config": {
        /* Additional configuration for your algorithm here */
        ...
      },

      /* Additional Learnosity adaptive config here */
      ...
    }
    ...
  }
}

For production implementations, Learnosity Support can also configure the engine_url in your Consumer Options, so it doesn't have to be publicly exposed.

Your service would need to support the following calls:

  • https://adaptive.example.com/v1/adaptive/oauth2/token: an endpoint supporting OAuth 2 with the client credentials grant flow for the selfhosted-adaptive scope. (By default, Learnosity will assume the OAuth 2 URL is <engine_url>/oath2/token, but you can override the path by providing the fully qualified URL to the adaptive.token_url parameter).

  • https://adaptive.example.com/v1/adaptive/getNextItems: an endpoint which Learnosity will call before and during the adaptive test. The endpoint should accept session details including the scores received for all previous Items seen in the student's test. The response payload contains a list of one or more Items that should be shown to the student next. See the detailed interface for /getNextItems defined below.

Optionally, your service can also operate on some persisted state that is passed to and from Learnosity in each subsequent call to /getNextItems. The state data can be mutated and returned in your response payload using the custom_state attribute, and Learnosity will pass this updated state data back on the next call to /getNextItems.

Note on semantic versioning

This API's versioning follows the Semantic Versioning 2.0.0 scheme: v<Major>.<minor>.<patch>. Generally speaking, this means that

  • patch is incremented on non-functional changes and bugfixes to this API (e.g., documentation or new optional request attributes);
  • minor is incremented when new features are added (e.g., new endpoints or mandatory request attributes);
  • Major is only incremented on breaking changes such as changes of request structure, removal of endpoints or attributes.

    Most importantly, this means that

  • all versions with identical Major and minor MUST accept and process the documented payload successfully;
  • any version with identical Major and larger-or-equal minor MUST be able to accept and process the documented payload of all smaller minor successfully;
  • no expectation is set as to the processing of payloads from different Majors.

    It is recommended that an implementation of this API checks that it can support the version specified in the requests (i.e., same Major, larger-or-equal minor than the request, any patch).

Learnosity will call this endpoint on your self-hosted adaptive service to get the next Item(s) for a session. This same endpoint is also called when the adaptive session is first initialized, to retrieve the first Item(s). In this case, the current_items array will be present and empty.

HTTP method: POST

Content-type: application/json

string (uuid)

The version number of this API. Used to identify the format of the request payload, and that expected in the response.

Only valid, and required, at the root level of the request

string (uuid)

A unique identifier for the client's request, for tracing purposes. Useful for debugging and other investigations, as the identifier is shown to the client on error.

Only valid at the root level of the request

Example: D32158D4-EB10-4D75-AC72-BA7292383D49
string (uuid)

The session ID, used to uniquely identify a user session and group subsequent requests within the same assessment.

Example: E439F6D7-15E4-4EBF-912F-EAA7CDB8171B
string (uuid)

The Activity ID, used to group Sessions which are taking the same Assessment.

Example: B44D81BE-BCE9-48B1-8A62-89E7BF1C772F
string (uuid)

The User ID, used to uniquely identify a given user across Sessions.

Example: CCDD021C-6F96-41D0-96EB-406D564B0DD3
object

The adaptive object from the Items API request object or Item Bank Activity Template, if applicable. This data is static for a given adaptive session, and will always contain the same data each time that session calls out to your adaptive backend.

Properties:
type
Type: string

The type of Adaptive engine to use (used by Items API). In this instance, only selfhosted is allowed.

Example: selfhosted
selfhosted_version_major
Type: string

The major version of the self-hosted Adaptive REST API supported by the Adaptive backend at engine_url.

Example: 1
engine_url
Type: string (url)

The base URL (no trailing slash) of the endpoint implementing this API. This instructs Items API about where to send the getNextItems requests.

If unspecified, Items API will use the preconfigured URL for the Learnosity API Consumer.

Example: https://adaptive.example.com/v1/adaptive
token_url
Type: string (url)

The URL of the endpoint offering an OAuth2 token from pre-shared client credentials.

If unspecified, Items API will use /oauth2/token on the base URL of the engine.

Example: https://authentication.example.com/oauth/adaptive/getToken
custom_config
Type: object

Configuration specific to your Adaptive backend. This should contain any configuration required by your algorithm to deliver the session.

Opaque to Learnosity

required_tags
Type: Array[object]

Only Items matching these tags from the Item Bank will be considered for presentation to the user.

Note: This is also used to select Items for automatic inclusion in Item pools alongside the Activity

Array[object]

All the Items already seen in the session. At the beginning of a session, the array should be present and empty.

Note: It is possible for Items to be removed from a session if a user resumes from an earlier save point.

Types
object
Properties:
reference
Type: string
Example: item-abc-123
organisation_id
Type: integer

The organisation ID of the Item Bank

Example: 1
item_pool_id
Type: string

The reference of the Item Pool

Example: MATH-2018
score
Type: number (float)
Example: 0.5
max_score
Type: number (float)
Example: 1
object

Container for optional custom state, persisted by Learnosity. The value provided here is the same value returned in the previous request for this session.

A response payload containing a list of one or more Items that should be shown to the student next.

HTTP status code: 200

Content-type: application/json

string (uuid)

The session ID, used to uniquely identify a user session and group subsequent requests within the same assessment.

Example: E439F6D7-15E4-4EBF-912F-EAA7CDB8171B
Array[object]

The next Items to be added to the session.

Types
object
Properties:
reference
Type: string
Example: item-abc-123
boolean

Instructs Items API to terminate the session after these Items are completed. Default to false.

object

Container for optional custom state, persisted by Learnosity. This value will be provided in the next request to this endpoint.

Opaque to Learnosity