SelfHosted Adaptive v1.0.0

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 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.

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

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

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

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

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

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.

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.

Container for optional custom state, persisted by Learnosity. The value provided here is the custom_state data currently persisted for this session. Set via the custom_state param of the most recent getNextItems response.

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

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

The next Items to be added to the session.

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

Container for optional custom state, persisted by Learnosity. The provided value will overwrite the custom_state data currently persisted for this session. This data will be sent in the next request to /getNextItems via the custom_state parameter.

Opaque to Learnosity