⏭️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:

Operation	v1 Endpoint	v2 Endpoint
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 data object to support additional metadata (see introduction of Pagination below).

Response Example:

Resource

GET /learners/1 <- Notice the Resource ID is now part of the URL

{
    "learner_id": 1,
    "first_name": "John",
    "last_name": "Smith",
    "gender": "M",
    "grade": "7",
    "debtor_code": "1001",
    "parent1_id": 40,
    "parent2_id": 41,
    "accountable_person_id": 40
}

Collection

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:

curl 'https://integrate.d6plus.co.za/api/v2/learners/1' \
     --header 'HTTP-X-USERNAME: yourusername' \
     --header 'HTTP-X-PASSWORD: yourpassword' \
     --header 'HTTP-X-SCHOOLID: 1234'

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:

Name	Type	Description
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 returned

• max_allowed_limit – The maximum number of records that can be requested per page

Response Example:

{
    "data": [
        ...
    ],
    "meta": {
        "limit": 10,
        "max_allowed_limit": 50,
        "next_cursor": "eyJpZCI6MTA4MDMsIl9iYWNrd2FyZCI6ZmFsc2V9"
    }
}

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.

v2

{
  "data": [    
    {
      "school_id": 1234,
      "name": "Greenwood High",
      "students_count": 450,
      "email_address": "[email protected]",
      "has_after_school_center": "Yes"
    },
    {
      "school_id": 1340,
      "name": "Riverside Academy",
      "students_count": 520,
      "email_address": null,
      "has_after_school_center": "No"
    }
  ]
}

v1

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:

v2 Create Response

POST /v1/notes

Status Code: 201 Created

Response Body:

{
    "success": true,
    "message": "Note created successfully",
    "data": {
        "note_id": 2543
    }
}

v1 Create Response

Delete Request Example:

v2 Delete Response

DELETE /v1/notes/2545

Status Code: 200 OK

Response Body:

{
    "success": true,
    "message": "Note deleted successfully"
}

v1 Delete Response

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:

v2 Not Found Error

Status Code: 404 Not Found

Response Body:

{
    "success": false,
    "message": "The note does not exist."
}

v1 Not Found Error

Validation Error Response Example:

v2 Validation Error

Status Code: 400 Bad Request

Response Body:

{
    "success": false,
    "message": "Validation Failed",
    "validation_errors": {
        "note_id": "The note_id is invalid",
        "date": "The Date is not valid date format. Expected format is 'Y-m-d'."
    }
}

v1 Validation Error

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.

Settings

1. Get Client Integrations

The API call named Settings/Clients has been renamed to Settings/ClientIntegrations, additionally the school ID does not form part of the URL anymore but moved to a query parameter.

Endpoint:

Old:

GET /v1/settings/clients(/{school_id})

New:

GET /v2/settings/clientintegrations(?school_id={school_id},...)

Response Body:

school_login_id changed to school_id

[
    {
        "school_id": 1000, // school_login_id -> school_id
        "school_name": "d6+ Primary School",
        "admin_email_address": "[email protected]",
        ...
    },
    ...
]

2. Update Client Integration

Similar to the "Get" call, the "Update" call was renamed from Settings/Clients to Settings/ClientIntegrations. The school ID does not form part of the URL anymore but moved to the request body. The request method also changed from PATCH to POST.

Endpoint:

Old:

PATCH /v1/settings/clients/{school_id}

New:

POST /v2/settings/clientintegrations

Request Body:

Old:

{
    "api_type_id": 8,
    "state": 1
}

New:

{
    "school_id": 1219, // <- now part of the request body
    "api_type_id": 8,
    "state": 1
}

Finance+

1. Get Learner Parent Info

The API call to get Learner Parent Info has been renamed to Learners.

Endpoint:

Old:

GET /v1/finplus/debtmanagement/learnerparentinfo/{school_id}(?learner_id=123)

New:

GET /v2/finplus/debtmanagement/learners(/{learner_id})

2. Get School Debtors

The API call to get School Debtors has been renamed to Accountable Persons.

Endpoint:

Old:

GET /v1/finplus/debtmanagement/schooldebtors/{school_id}
(?accountable_person_id=123)

New:

GET /v2/finplus/debtmanagement/accountablepersons(/{accountable_person_id})