Specifications

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",
      "selfhosted_version_major": 1,
      "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>/oauth2/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 learner's test. The response payload contains a list of one or more Items that should be shown to the learner 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).

Download the full specification (OpenAPI).