WordPress 5.6 bringt ein Framework mit, das es ermöglicht, mit einem Request an den Server mehrere REST-API-Anfragen zu machen. So müssen sich Entwicklerinnen und Entwickler nicht mehr damit auseinandersetzen, mehrere asynchrone Requests an die API abzuschicken.
Außerdem ist es möglich, sicherzustellen, dass die übergebenen Aufrufe alle valide sind, bevor sie ausgeführt werden.
REST-Endpunkt für Batch-Requests freischalten
Ein REST-Endpunkt muss für die Nutzung in Batch-Requests freigeschaltet werden. Dafür wird der allow_batch-Schlüssel beim Aufruf von register_rest_route() mitgegeben:
register_rest_route( 'namespace/v1', 'route', [
// die weiteren Argumente.
'allow_batch' => [ 'v1' => true ],
] );Code-Sprache: PHP (php)Um jetzt einen Stapel an Aufrufen an diesen Endpunkt zu schicken, wird ein POST-Request an https://example.com/wp-json/batch/v1 ausgeführt. Der Request bekommt in requests ein Array von Anfrageobjekten übergeben, und die Daten so eines Objekts können beispielhaft so aussehen:
{
"requests": [
{
"method": "POST",
"path": "/namespace/v1/route/1",
"headers": {
"Header-1": "value",
},
"body": {
"title": "Batch requests"
}
}
]
}Code-Sprache: JSON / JSON mit Kommentaren (json)Von den folgenden Schlüsseln aus dem Anfrageobjekt muss nur path in jedem Fall angegeben werden, alle anderen sind optional.
- Die HTTP-Methode
methodist standardmäßig aufPOSTgesetzt. pathist der Pfad zum Endpunkt, optional können auch Query-Parameter angehängt werden.headerssind HTTP-Header, die der Anfrage mitgegeben werden. Als Wert ist hier auch ein Array von mehreren Werten für einen Header möglich.bodyenthält die Parameter für die Anfrage, beispielsweise der Titel für einen Beitrag.
Maximale Anzahl von Requests
Standardmäßig ist die maximale Anzahl von Requests in einem Batch auf 25 eingestellt. Der Wert kann aber über den rest_get_max_batch_size-Filter angepasst werden, weshalb vor der ersten Anfrage die Maximalanzahl abgefragt werden sollte.
Das geht mit einem OPTIONS-Request an https://example.com/wp-json/batch/v1, der ein Objekt mit allerlei Informationen zurückliefert. Das ist das Ergebnis von meiner Site:
{
"namespace": "",
"methods": [
"POST"
],
"endpoints": [
{
"methods": [
"POST"
],
"args": {
"validation": {
"type": "string",
"enum": [
"require-all-validate",
"normal"
],
"default": "normal",
"required": false
},
"requests": {
"type": "array",
"maxItems": 25,
"items": {
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"POST",
"PUT",
"PATCH",
"DELETE"
],
"default": "POST"
},
"path": {
"type": "string",
"required": true
},
"body": {
"type": "object",
"properties": [],
"additionalProperties": true
},
"headers": {
"type": "object",
"properties": [],
"additionalProperties": {
"type": [
"string",
"array"
],
"items": {
"type": "string"
}
}
}
}
},
"required": true
}
}
}
],
"_links": {
"self": [
{
"href": "https://florianbrinkmann.com/wp-json/batch/v1"
}
]
}
}Code-Sprache: JSON / JSON mit Kommentaren (json)In endpoints[0].args.requests.maxItems ist der Wert für die maximalen Requests in einem Batch angegeben.
Antworten und Validierung
Als Antwort auf einen Batch-Request bekommen wir einen 207-Statuscode sowie die Antworten auf jeden Request im Batch in derselben Reihenfolge wie in der Anfrage.
Um Anfragen zu validieren, kann ein validate_callback und sanitize_callback genutzt werden. Diese können für jeden Parameter einzeln definiert werden (wie auf der Handbook-Seite Adding Custom Endpoints im Abschnitt Arguments beschrieben), und/oder seit WordPress 5.6 kann auch ein validate_callback für einen REST-Endpunkt auf dem obersten Level definiert werden, der dann wie der callback das gesamte Request-Objekt als Parameter erhält.
Wenn diese Funktionen einen Fehler zurückgeben, kann bei Bedarf ein gesamtes Batch zurückgewiesen werden. Dazu muss der validation-Key in der Batch-Anfrage auf require-all-validate gesetzt werden:
{
"validation": "require-all-validate",
"requests": [
{
"_request1": ""
},
{
"_request2": ""
}
]
}Code-Sprache: JSON / JSON mit Kommentaren (json)Wenn require-all-validate eingesetzt ist, wird in der Antwort für valide Anfragen null zurückgegeben, und für fehlerhafte Anfragen ein Fehler.
Mehr Informationen zu dem Thema, etwa zu den Einschränkungen (momentan unterstützt noch kein Core-Endpunkt Batch-Anfragen) findet ihr in der Dev-Note REST API Batch Framework in WordPress 5.6.
Mentions