REST Responses¶
What is this?¶
As the client and the server are completely separated, they need to have a way communicated. It is basically a standardized way of transfering, in our case JSON data, from the server to the client.
How to use this?¶
The REST response pipeline is the Rest class, but you'll typically reach for one of the response helpers instead:
| Call | Purpose |
|---|---|
$res->generateRest |
Sends a REST payload wrapped in a meta envelope and exits by default |
$res->generateRestError |
Logs a REST_ERROR warning, sends only the error object and exits (HTTP status stays 200) |
$res->error |
Convenience for generateRest with result=error and the message, an optional payload array is merged like success does, exits |
$res->success |
Convenience for generateRest with result=success, exits; payload keys are merged after result and can override it |
$res->formErrors |
Merges all array arguments (others are ignored) into {"result":"formErrors","formErrors":[...]} inside the meta envelope, exits; each entry holds name, type and optional info |
$res->json |
Sends a raw JSON payload (no meta wrapper); does not exit |
generateRest takes a payload array whose keys are added after meta (a payload key named meta replaces it). The second parameter of generateRest called $die determines if the script exits after generating the REST response. The parameter is optional with a default value of true. The pretty-printed JSON is sent without an HTTP status code. Its Content-Type follows the Accept header of the request: a client that names application/json there (jQuery with dataType: "json", an API client) gets application/json, every other client gets text/plain; charset=utf-8, never text/html. A plain $.post() therefore still receives text, and code that calls JSON.parse() on it keeps working. A Content-Type the application has set itself beforehand is kept. Z.Request and Z.Forms accept text as well as the object jQuery makes of an application/json reply; Z.Request.parseAnswer(data) does the same for own code. Text in the payload that is not valid UTF-8 (from a file that was not converted, or a character cut in half by substr()) is sent with the broken bytes replaced by \uFFFD, so the reply still arrives. A number that cannot be encoded (NAN, INF) throws a \JsonException and sends nothing.
Example Calls¶
generateRest¶
$res->generateRest([
"response" => "RESPONSE",
"error" => "ERROR"
]);
{ "meta": { "endpoint": "REST API", "request": "URL", "timestamp": 9999999 }, "response": "RESPONSE", "error": "ERROR" }
generateRestError¶
$res->generateRestError(404, "MESSAGE");
{ "error": { "code": 404, "message": "MESSAGE" } }
success¶
$res->success([
"information" => "MESSAGE"
]);
{ "meta": { "endpoint": "REST API", "request": "URL", "timestamp": 9999999 }, "result": "success", "information": "MESSAGE" }
error¶
$res->error("MESSAGE");
{ "meta": { "endpoint": "REST API", "request": "URL", "timestamp": 9999999 }, "result": "error", "message": "MESSAGE" }
json¶
Use json when you need to send a raw JSON payload without the REST meta wrapper. It sets Content-Type: application/json (and no status code) and echoes json_encode($data). Unlike the other helpers above it does not exit — call exit yourself if you need to stop the request here. JSON_THROW_ON_ERROR is always applied, so unencodable values raise a JsonException, after the header was already set.
$res->json([
"ok" => true,
"items" => [1, 2, 3],
]);
{"ok":true,"items":[1,2,3]}
Pass extra json_encode options as the second argument:
$res->json($data, JSON_PRETTY_PRINT);