Eine saubere JSON-API in PHP – richtig antworten und Eingaben lesen

Wenn ich für eine App oder ein Frontend einen kleinen Endpoint in PHP baue, gehört zu einer sauberen JSON-Antwort mehr als echo json_encode(...). Der richtige Header und ein passender Statuscode machen den Unterschied.

Sauber antworten

<?php
declare(strict_types=1);

function json_response(array $data, int $status = 200): never
{
    http_response_code($status);
    header('Content-Type: application/json; charset=utf-8');
    echo json_encode($data, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
    exit;
}

Content-Type: application/json sagt dem Client, was kommt – ohne ihn interpretiert der Browser die Antwort als Text. JSON_UNESCAPED_UNICODE hält Umlaute lesbar, JSON_THROW_ON_ERROR wirft bei kaputten Daten eine Exception statt still ein leeres false zu liefern.

Den JSON-Body einer Anfrage lesen

Anders als bei Formularen steht ein JSON-Request nicht in $_POST. Du liest ihn aus dem rohen Input-Stream:

$raw = file_get_contents('php://input');
try {
    $input = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException) {
    json_response(['error' => 'Ungültiges JSON'], 400);
}

$name = trim((string)($input['name'] ?? ''));
if ($name === '') {
    json_response(['error' => 'name fehlt'], 422);
}

json_response(['ok' => true, 'name' => $name], 201);

Die richtigen Statuscodes

• 200 ok · 201 angelegt · 400 kaputte Anfrage
• 401/403 nicht eingeloggt / verboten · 404 nicht gefunden
• 422 valide JSON, aber inhaltlich falsch (Feld fehlt) · 500 Serverfehler

Ein Client (z. B. fetch) prüft response.ok anhand dieses Codes – gib also nie „alles 200" zurück, wenn etwas schiefging.

Genau so baue ich die Backends für die Apps meiner Kunden. Brauchst du eine solide API? Schreib mir über bymw.de.

Quellen

• json_encode — php.net
• http_response_code — php.net