8 posts tagged with "Breaking"

Paging by page has been removed​

The page parameter no longer exists on any list endpoint. Every list is paged with cursor. This is a breaking change to any request that still sends page.

Read cursor from the response and send it back to fetch the next page; omit it to start from the beginning. pageSize is unchanged and still sets how many records a page holds. Paging by cursor is forward-only, so there is no page number to jump to and no total to divide.

Before:

GET /api/v1/invoices?page=3&pageSize=25

After:

GET /api/v1/invoices?cursor=CURSOR_FROM_PREVIOUS_RESPONSE&pageSize=25

Resource items: locationId is replaced by a locations collection​

On GET /api/v1/resource-items and GET /api/v1/resource-items/{id}, the single locationId field is gone. A resource item now returns locations, a list of the locations it is available at, each with an id, a name and a link. This is a breaking change to the resource item response.

A resource can be shared across locations, which the single field could not express. Read resourceItem.locations and match on the entry you need instead of comparing locationId. The locationId filter on the list endpoint is unchanged and now matches an item at any of its locations.

Before:

"locationId": 3

After:

"locations": [
  {
    "id": 3,
    "name": "Coburg",
    "links": [{ "href": "/api/v1/locations/3", "rel": "self", "method": "GET" }]
  },
  {
    "id": 7,
    "name": "Fitzroy",
    "links": [{ "href": "/api/v1/locations/7", "rel": "self", "method": "GET" }]
  }
]

Referrals: referrerType is now an object​

On GET /api/v1/referrals and GET /api/v1/referrals/{id}, the referrerType field has changed from a plain text name to an object with an id, a name, and a link to the matching referrer type. This is a breaking change to the referral response.

If you currently read the referrer type's name, change referral.referrerType to referral.referrerType.name. You can now also use referral.referrerType.id to fetch it from GET /api/v1/referrer-types/{id}, or match it against the GET /api/v1/referrer-types list. As before, referrerType is null when a referrer has no type set.

Before:

"referrerType": "General Practitioner"

After:

"referrerType": {
  "id": 42,
  "name": "General Practitioner",
  "links": [{ "href": "/api/v1/referrer-types/42", "rel": "self", "method": "GET" }]
}

Note and form templates​

• GET /api/v1/note-templates lists the practice's note templates.
• GET /api/v1/form-templates and GET /api/v1/form-templates/{id} list and fetch form templates.

Invoices: PATCH takes insurer ids, not client-insurer ids​

On PATCH /api/v1/invoices/{id}, the request field clientInsurerIds is renamed to insurerIds, and the values it accepts have changed: pass insurer ids, not the ids of the client-insurer link records. This is a breaking change to the invoice update request.

Take the ids from the insurer resource rather than from the client's insurer list. A request still sending clientInsurerIds is rejected.

All write endpoints: malformed request bodies are rejected​

Request bodies used to be accepted silently when they carried fields the API did not recognise, or the same field twice. Both now fail with 400 Bad Request and a code of InvalidRequestBody. This is a breaking change to every POST, PUT and PATCH endpoint.

An unknown field, clientIdd for clientId, used to be ignored, so the value you thought you were setting was quietly dropped. A body containing the same property twice used to keep the last one, with no way to tell which had been applied. Both are now errors.

Field names are compared case-insensitively for the duplicate check, so clientId and ClientID in one body is also rejected. Review any payload built by string concatenation, or merged from more than one source.

Appointments: cancellationReason is now an object​

On GET /api/v1/appointments and GET /api/v1/appointments/{id}, cancellationReason has changed from a plain text name to an object with an id, a name and a link to the matching reason. This is a breaking change to the appointment response.

If you read the reason's text, change appointment.cancellationReason to appointment.cancellationReason.name. You can now also match it against GET /api/v1/cancellation-reasons. As before, it is null when the appointment was not cancelled.

Before:

"cancellationReason": "Client unwell"

After:

"cancellationReason": {
  "id": 7,
  "name": "Client unwell",
  "links": [{ "href": "/api/v1/cancellation-reasons/7", "rel": "self", "method": "GET" }]
}

Cancellation reasons and appointment flags​

GET /api/v1/cancellation-reasons and GET /api/v1/appointment-flags list the practice's cancellation reasons and appointment flags, each with a by-id endpoint.

Referrals: startDate and endDate are dates, not date-times​

On GET /api/v1/referrals and GET /api/v1/referrals/{id}, the two referral dates are returned as plain dates rather than as timestamps at midnight. The matching filters, startDateFrom, startDateTo, endDateFrom and endDateTo, accept a plain date too. This is a breaking change if you parse either field as a date-time.

A referral begins and ends on a day, not at an instant, so the time component was always zero and the timezone it implied was misleading. Parse both fields as dates, and send dates when you filter. Both remain null when the referral has no such date set.

Before:

"startDate": "2026-06-15T00:00:00Z"

After:

"startDate": "2026-06-15"

Invoices: deep pages timed out​

Requesting a high page number from GET /api/v1/invoices could take long enough to fail with a server error rather than return.

Paged responses: totalItemCount and pageCount are gone, and pageNumber is now page​

The envelope every list endpoint returns has changed. pageNumber is renamed to page, and the two totals, totalItemCount and pageCount, have been removed. This is a breaking change to every list endpoint.

Counting the whole result set on every request is what made large lists slow, and no total can be returned without doing it. To walk a list, read hasNextPage and request the next page while it is true, rather than dividing a total by your page size. If you display a count, you will need to stop showing one, or count what you have fetched. items, links and pageSize are unchanged.

Before:

{
  "pageNumber": 1,
  "pageSize": 10,
  "totalItemCount": 438,
  "pageCount": 44,
  "hasNextPage": true
}

After:

{
  "page": 1,
  "pageSize": 10,
  "hasNextPage": true
}