Data API v1 includes the following enhancements:

• Improved performance and stability, especially for item and session retrieval.
• Simple and powerful new item definition format for importing and manipulating item content.
• A more consistent API for status polling and session data.

 

This guide contains important information about the changes between Data API v0.x and v1.0 to help customers plan their upgrade. The following sections describe general changes affecting many endpoints, as well as localised changes for specific endpoints.

 

Filtering controls

To provide clearer guidance on Data API GET performance, we now accept up to 1000 identifiers in any GET filter parameter. This limit applies to the following filter parameters:

• itembank/activities: references
• itembank/items: references, questions.references, questions.types
• itembank/questions: references, item_references, types
• itembank/features: references, item_references, types
• itembank/pools: references
• sessions/statuses: activity_id, user_id, session_id
• sessions/scores: activity_id, user_id, session_id
• sessions/responses: activity_id, user_id, session_id
• sessions/responses/scores: activity_id, user_id, session_id
• sessions/reports/adaptive: activity_id, user_id, session_id

 

If your use case requires passing more than 1000 identifiers for any of these filters, we advise splitting the list of identifiers into batches of 1000 and making separate calls to the SDK's requestRecursive() method for each batch of identifiers.

Note: the limit of 1000 identifiers applies to version 1.3+. Versions 1.0-1.2 accept up to 50 identifiers.

Result limits

To improve overall stability of the Data API, most endpoints now support a maximum limit of 50 results per request. 50 is also used as the default if no limit is specified in the request. Use the SDK's requestRecursive() to easily retrieve larger result sets. This limit applies to the following endpoints:

• GET itembank/activities
• GET itembank/items
• GET itembank/questions
• GET itembank/features
• GET itembank/pools
• GET sessions/statuses
• GET sessions/scores
• GET sessions/responses
• GET sessions/responses/scores
• GET sessions/reports/adaptive
• GET jobs

 

Unified item statuses, session statuses

For consistency and usability, the itembank/* and sessions/* endpoints now operate with a consistent set of statuses.

The following statuses apply to itembank/activities and itembank/items:

• "Published"
• "Unpublished"
• "Archived" (was "Deleted")

 

The following statuses apply to sessions/statuses, sessions/scores, sessions/responses, sessions/responses/scores and sessions/responses/adaptive

• "Completed"
• "Corrected"
• "Incomplete" (was "Started")
• "Discarded"
• "Pending Scoring"

 

The new statuses are expected and validated in SET requests, GET filters and resultsets.

Itembank endpoints

itembank/activities

• Complies with unified itembank statuses.
• like and include_base parameters are no longer available in GET requests.

itembank/items

• SET itembank/items now accepts a new and much more powerful definition parameter for importing item content. See the Item Definition section for details.
• The content parameter is no longer available on SET itembank/items or GET itembank/items - use definitioninstead.
• GET itembank/items now uses ”split_feature_references”: true by default. This returns separate arrays of questions and features associated with each item, and includes the question type/feature type of each.
• Complies with unified itembank statuses.

itembank/questions

• Now returns question widgets only. Feature widgets can be retrieved from the dedicated itembank/features endpoint.

itembank/activities/base

• This endpoint is no longer available. Use itembank/activities/templates instead.

Sessions endpoints

sessions/statuses

• Significantly improved performance.
• New GET response format aligns with the other sessions endpoints. Contains one result object per session with dt_started and dt_completed values for the started and completed times of the session. The status value always reflects the latest status of the session.
• Complies with unified sessions statuses.
• school_id no longer available in GET requests or resultsets.

sessions/scores

• Complies with unified sessions statuses.
• school_id no longer available in GET requests or resultsets.

sessions/responses

• Changed the type of the automarkable flag on each response - was integer, now boolean.
• school_id no longer available in GET requests or resultsets.

sessions/responses/scores

• school_id no longer available in GET requests or resultsets.

sessions/reports/adaptive

• Added support for filtering by session_id, user_id and session status.
• Complies with unified sessions statuses.
• school_id no longer available in GET requests or resultsets.

sessions/reports

• This endpoint is no longer available. Use Reports API or the other sessions endpoints for your reporting requirements.

users/*

• These endpoints are no longer available. Retrieve user sessions from the sessions endpoints instead.

schools/*

• These endpoints are no longer available. school_id is no longer supported in Data API v1.