API Update Coming Soon: laravel-json-api v4 to v5.x

⚠️ Sign up for our API Mailing list here to receive updates about future API changes.

📦 Coming Soon: API Framework Upgrade to Laravel JSON:API v5.x

Planned Release Date: Early January 30th, 2026 during our scheduled maintenance window [12am-2am EST]

🔧 What’s Changed

We’re preparing to upgrade our internal API framework from cloudcreativity/laravel-json-api v4.0.x to v5.x. This change ensures long-term stability, unlocks future upgrade paths, and keeps our platform aligned with the latest improvements in the JSON:API ecosystem.

💥 What This Means for You

Most customers will not need to make any changes to continue using the API. However, if you’re building custom integrations or handling raw API responses, please review the Laravel JSON:API v5 Upgrade Guide for deeper insights into the changes under the hood.

🔍 Notable Improvements:

• Improved performance and better alignment with the latest JSON:API specification
• Cleaner internal handling of resource objects and relationships
• Enhanced support for custom query parameters and validation

⚠️ Breaking Changes

While we aim to preserve backward compatibility, some behavioral changes in v5 may impact custom consumers:

1. Relationship Format Standardization

What Changed: Empty relationships are now serialized as {"data": null} instead of empty arrays [], in line with the JSON:API spec.

Before (v4):

{
"relationships": {
  "employee": [],
  "role": [],
  "facilities": []
 }
}

After (v5):

{
"relationships": {
  "employee": { "data": null },
  "role": { "data": null },
  "facilities": { "data": null }
 }
}

Examples Affected (all endpoints returning empty relationships):

• api_v1_employee-roles_id/get-valid-token.response
• api_v1_program-types/get-valid-token.response
• api_v1_addresses/get-valid-token.response

Client Impact:

• Clients checking for relationship === [ ] must update logic to check relationship.data === null
• Slight increase in response size (~33 bytes per empty relationship)

Recommendations:

• Update client-side relationship parsing logic accordingly
• Consider reviewing all endpoints with dynamic relationship handling

2. Error Object Simplification

What Changed: Error responses no longer include code or meta fields. This results in more secure, minimal responses, but also removes detailed debug information.

Before (v4):

{
"errors": [{
  "status": "404",
  "code": "0",
  "title": "Not Found",
  "detail": "The route ... could not be found.",
  "meta": {
    "exception": "NotFoundHttpException",
    "file": "...",
    "trace": [...]
  }
}]

After (v5):

{
"errors": [{
  "status": "404",
  "title": "Not Found",
  "detail": "The route ... could not be found."
 }
}]

Examples Affected (all error responses across the API):

• api_company_v1_auth_token/post-expired-token.response
• api_company_v1_company_auth_token/post-invalid-token.response
• api_company_v1_customer_auth_token/post-no-token.response

Client Impact:

• Any client code that parses error.code or error.meta will break
• Less visibility into internal errors unless separately logged

Recommendations:

• Remove any client-side dependencies on error.code or meta
• Ensure server-side logging captures detailed error traces