Upgrading to v2
This page highlights the key changes introduced in API v2 and serves as a reference for upgrading from v1.
1. Adoption of Collections vs. Resources
In v2, our API follows RESTful principles more strictly by differentiating between Collections and Resources. A Collection represents a group of items whereas a Resource represents a specific item.
In v1, the API structure included the School ID as the last segment of the URL, and when retrieving a specific item. The ID was passed either as a query parameter or was included in the request body.
In v2, the API structure follows a more RESTful approach:
Resources now have their ID passed in the URL (e.g.,
/learners/{learner_id}).Collections exclude the ID and are retrieved using a general endpoint (e.g.,
/learners).
Request Example:
Get all learners
/learners/{{SCHOOL_ID}}
/learners
Get a specific learner
/learners/{{SCHOOL_ID}}?learner_id=123
/learners/123
This change also impacts the response payload structure:
In v1, all responses that contained data were returned as an array, even when fetching a single item.
In v2, the response format aligns with RESTful design:
A Resource request returns a single object.
A Collection request returns an array, wrapped inside a
dataobject to support additional metadata (see introduction of Pagination below).
Response Example:
GET /learners/1 <- Notice the Resource ID is now part of the URL
2. School ID Moved to Request Headers
In light of the above changes to the API, the School ID moved to the request headers. This is to accommodate the changes for the adoption of a collection versus a resource design (see above).
In example:
3. Pagination Introduced
Version 2 of the Integrate API adopted pagination to help improve server performance and reduce response times. We've adopted the cursor-based pagination strategy, which uses an opaque string to mark the starting point for the next set of items.
The following query parameters allows you to control pagination:
cursor
String
To retrieve the next group of items
limit
Integer
To override the default limit of records returned (up to the max_allowed_limit provided in the response metadata).
reverse_order
Boolean
To sort the results in descending order (useful for fetching the latest records first).
The response payload now includes a meta object containing pagination-related data.
next_cursor– The cursor to use for retrieving the next set of items. If no further data is available, this field is omitted.limit– The number of records returnedmax_allowed_limit– The maximum number of records that can be requested per page
Response Example:
4. Correct Type-Casting in Response Body
In v1, all response fields were returned as strings, regardless of their actual data type. This required clients to manually parse numbers, booleans, and other data types.
In v2, all fields in the response body are now properly type-casted to their correct data types, reducing processing overhead and improving API consistency.
5. Success Responses Updated
The success response format has been updated to a more standardized format.
The response fields are as follows:
success– Indicates whether the request was successful.message– A success confirmation message.data– An object that contains the ID of the item that has been created. Additional fields of the created item may be included in the data object if necessary.
Create Request Example:
POST /v1/notes
Status Code: 201 Created
Response Body:
Delete Request Example:
DELETE /v1/notes/2545
Status Code: 200 OK
Response Body:
6. Error responses updated
Similar to the success responses, the error response format has also been updated to provide a more consistent format across the API.
The response fields are as follows:
success– Indicates whether the request was successful.message– A success confirmation message.
In the event of a user input validation failure, the following will be included in the response body:
validation_errors– A list of fields and the validation error message
Not Found Error Example:
Status Code: 404 Not Found
Response Body:
Validation Error Response Example:
Status Code: 400 Bad Request
Response Body:
To ensure backward compatibility, some existing errors that were previously returned in v1 may still use the old response format. However, all newly introduced errors follow the updated structure, making it easier to handle and interpret responses moving forward.
7. Changes to Individual API Calls
In addition to the changes mentioned above, this section outlines specific updates to API endpoints and fields introduced in v2. These updates align the API more closely with RESTful principles.
Last updated