Response format#

🔴 The most important chapter in this manual. Read it before writing a parser.

Two different shapes#

Reads and writes return different structures

A read has no success field. A write has one. A single parser keyed on success is not possible.

Reading a collection#

{
  "items": [
    { "id": { "id": 5 } },
    { "id": { "id": 6 } }
  ],
  "totalCount": 42,
  "_references": {
    "App\\UI\\Api\\Blog\\Models\\Entities\\Article": {
      "5": { "id": 5, "title": "…", "category": { "id": { "id": 3 } } },
      "6": { }
    },
    "App\\UI\\Api\\Blog\\Models\\Entities\\Category": {
      "3": { }
    }
  }
}

items holds references, not data

The actual values are in _references, keyed by the full class name and the identifier. A client must dereference the references; otherwise, it gets only numbers.

References inside _references are references again — dereferencing is recursive.

A composite identifier key is joined with a hyphen

For example "3-7".

totalCount is zero until you ask for it

Send computeTotalCount=1. So zero does not mean "nothing found".

Reading one record#

{
  "data": { "id": { "id": 5 } },
  "_references": { }
}

Not found returns an empty array, not an error

[]

With HTTP 200. Not HTTP 404 and not success: false.

Writing#

{
  "success": true,
  "message": null,
  "exception": null,
  "data": { },
  "code": 0
}

The key order is fixed. code is a numeric result code; zero means success.

The write response is incomplete

It returns only flat values of the saved entity — no nested collections and no identifiers of newly created children. After writing with relations, read the data back with includes.

An error envelope may not carry all five keys

Some error paths return only three. Do not rely on exception or data being present.

Pagination#

No links and no cursors. Just offset and limit in the query and totalCount in the response.

Content type#

404 and 500 return HTML, not JSON

A non-existent resource or an unhandled exception returns an error page. Your parser must check Content-Type or it will choke on invalid JSON.

Recommended processing#

Check Content-Type — if it is not JSON, it is a server error.
Check the status code: handle 401, 403 and 429 separately.
If the response has success, it is a write — decide by it and by code.
If it does not, it is a read — dereference _references.