Mit der REST-API arbeiten

Tutorial · Easy SVG

Easy SVG registriert sieben REST-Routen im Namensraum easy-svg/v1. Das Icons-Panel im Backend nutzt sie, um die Einstellungen zu lesen und zu speichern und um Icons hinzuzufügen, umzubenennen, neu zu zeichnen und zu löschen. Dieses Tutorial zeigt dir, wie du dieselben Routen selbst aufrufst, aus dem Terminal, aus einem Deployment-Skript oder aus deinem eigenen Admin-JavaScript, und was jede Route annimmt und antwortet.

Die Routen auf einen Blick

Alle werden auf rest_api_init von easy_svg_panel_rest() in includes/panel.php registriert. Die Routen sind immer da, egal ob der Schalter für die Icon-Bibliothek an ist oder nicht (mehr dazu unter Stolperfallen).

Anmeldung

Jede Route braucht einen angemeldeten Benutzer. Dafür gibt es zwei Wege.

curl https://example.com/wp-json/easy-svg/v1/settings \
	-u admin:'abcd efgh ijkl mnop qrst uvwx'

add_action( 'admin_enqueue_scripts', 'myaddon_enqueue_icon_tools' );

function myaddon_enqueue_icon_tools( $hook_suffix ) {
	if ( 'tools_page_myaddon-icons' !== $hook_suffix ) {
		return;
	}

	wp_enqueue_script(
		'myaddon-icon-tools',
		plugins_url( 'js/icon-tools.js', __FILE__ ),
		array( 'wp-api-fetch' ),
		'1.0.0',
		true
	);
}

wp_add_inline_script(
	'myaddon-icon-tools',
	'window.myaddonRest = ' . wp_json_encode(
		array(
			'root'  => esc_url_raw( rest_url( 'easy-svg/v1/' ) ),
			'nonce' => wp_create_nonce( 'wp_rest' ),
		)
	) . ';',
	'before'
);

So sieht eine gescheiterte Anmeldung aus:

Berechtigungen

Jede Route, ob lesend oder schreibend, nutzt denselben Permission-Callback, easy_svg_panel_rest_permission(). Er ist eine Zeile lang:

function easy_svg_panel_rest_permission(): bool {
	return current_user_can( 'manage_options' );
}

Daraus folgen drei Dinge:

• Es ist manage_options, nicht edit_theme_options. Der Icon-Beitragstyp selbst verlangt EASY_SVG_ICON_CAP (edit_theme_options), die REST-Routen verlangen mehr. Wer Theme-Optionen bearbeiten, aber keine Optionen verwalten darf, kommt nicht an sie heran.
• Die Berechtigungen der Panel-Tabs zählen hier nicht. Ein Add-on kann einem Tab eine eigene Berechtigung geben (siehe easy_svg_panel_tab_capabilities()). Das entscheidet nur, welche Tabs und Menüeinträge jemand sieht. Die REST-Routen prüfen trotzdem manage_options.
• Auch die lesenden Routen sind nur für Admins. GET /settings und GET /library sind nicht öffentlich, weil die Bibliotheksantwort das Markup jedes Icons enthält.

In einem Multisite-Netzwerk wird manage_options auf der Website geprüft, an die die Anfrage geht. Ein Website-Administrator kann die Routen also auf seiner eigenen Website nutzen.

Wie eine Anfrage verarbeitet wird

Die Reihenfolge zu kennen hilft, denn welcher Fehler zurückkommt, hängt davon ab, welcher Schritt abgelehnt hat.

WordPress prüft die Argumente, bevor es die Berechtigung prüft. Eine Anfrage, der ein Pflichtfeld fehlt, antwortet mit 400, auch wenn niemand angemeldet ist. Lies eine 400 also nicht als "meine Zugangsdaten stimmen".

Jeder POST-Handler liest den JSON-Body und sonst nichts. Jeder beginnt mit $request->get_json_params(). WordPress füllt das nur, wenn die Anfrage Content-Type: application/json mitschickt. Das hat eine fiese Folge: Die Schemaprüfung in Schritt C schaut an jeder Stelle, an der ein Parameter stehen kann (JSON-Body, Formular-Body, Query-String), der Handler aber nur in den JSON-Body. Eine Anfrage kann die Prüfung also bestehen und trotzdem leer beim Handler ankommen:

# Besteht das Schema (id=42 steht im Query-String),
# aber der Handler sieht keinen JSON-Body, liest id als 0 und antwortet 404.
curl -X POST 'https://example.com/wp-json/easy-svg/v1/library/delete?id=42' \
	-u admin:'abcd efgh ijkl mnop qrst uvwx'

Die Lösung ist immer dieselbe: Schick die Felder als JSON, mit dem Header.

curl -X POST https://example.com/wp-json/easy-svg/v1/library/delete \
	-u admin:'abcd efgh ijkl mnop qrst uvwx' \
	-H 'Content-Type: application/json' \
	-d '{"id":42}'

Die einzige Ausnahme ist GET /library, das search wie jede GET-Route aus dem Query-String liest.

WordPress wandelt die Typen um, bevor der Handler läuft. Weil die Routen ihre Argumente deklarieren, bereinigt WordPress die JSON-Werte auf den deklarierten Typ. Aus "id":"42" wird die Zahl 42, aus "icons":"false" das Boolean false. Ein Wert, der sich nicht umwandeln lässt ("id":"abc", "icons":"vielleicht", "max_mb":2.5), wird mit 400 rest_invalid_param abgelehnt.

Fehlerantworten

Jeder Fehler, ob von WordPress oder von Easy SVG, hat die übliche WordPress-Form:

{
	"code": "easy_svg_add_failed",
	"message": "That name cannot be turned into an icon name. Use letters and numbers.",
	"data": {
		"status": 422
	}
}

Schemafehler von WordPress bringen zusätzlich ein Objekt params mit, das das Feld nennt:

{
	"code": "rest_invalid_param",
	"message": "Invalid parameter(s): id",
	"data": {
		"status": 400,
		"params": {
			"id": "id must be greater than or equal to 1"
		}
	}
}

Entscheide anhand von code und data.status. Zeig message den Leuten, aber werte den Text nie aus: Er ist übersetzt.

Die Bibliotheksantwort

Sechs der Routen antworten mit demselben Objekt: der aktuellen Icon-Liste. Sie wird von easy_svg_panel_library_payload() gebaut und immer direkt aus der Datenbank gelesen, nie aus dem Icon-Cache. Sie zeigt also schon den Schreibvorgang, den du gerade gemacht hast.

Blättern gibt es nicht. Icons nach dem 500. erreichst du über diese Routen nicht, nur eine engere Suche (search) zeigt sie.

Einstellungen: GET und POST /settings

Liest oder speichert die drei Werte auf dem Tab Einstellungen des Panels. Vollständige Referenz: rest-settings.

GET nimmt keine Argumente und gibt easy_svg_settings() zurück. POST führt den JSON-Body mit dem Gespeicherten zusammen, schickt das Ergebnis durch easy_svg_sanitize_settings(), speichert es und gibt die Einstellungen so zurück, wie sie jetzt sind. Ein Schlüssel, den du weglässt, behält seinen gespeicherten Wert, ein ausdrückliches false schaltet eine Funktion ab.

# Lesen
curl https://example.com/wp-json/easy-svg/v1/settings \
	-u admin:'abcd efgh ijkl mnop qrst uvwx'

# Icon-Bibliothek einschalten, den Rest in Ruhe lassen
curl -X POST https://example.com/wp-json/easy-svg/v1/settings \
	-u admin:'abcd efgh ijkl mnop qrst uvwx' \
	-H 'Content-Type: application/json' \
	-d '{"icons":true}'

const settings = await wp.apiFetch( { path: '/easy-svg/v1/settings' } );

// 50 MB anfragen. Mit der Standardgrenze von 20 sagt die Antwort 20.
const saved = await wp.apiFetch( {
	path: '/easy-svg/v1/settings',
	method: 'POST',
	data: { max_mb: 50 },
} );

if ( saved.max_mb < 50 ) {
	console.info( `Auf die Obergrenze gesetzt: ${ saved.max_mb } MB` );
}

Gut zu wissen:

• Änderungen wirken ab der nächsten Anfrage. Upload- und Icon-Funktion werden eingehängt, wenn easy-svg.php lädt. Die Anfrage, die icons: true speichert, läuft also noch ohne Icon-Bibliothek. Die Antwort zeigt den neuen Wert trotzdem schon.
• Unbekannte Schlüssel fallen weg. Der Sanitizer gibt nur svg_upload, icons und max_mb zurück.
• Ein POST als Formular tut stillschweigend nichts. Der Handler sieht einen leeren JSON-Body, führt nichts zusammen und antwortet 200 mit den unveränderten Einstellungen.

Icons auflisten: GET /library

Vollständige Referenz: rest-library.

curl 'https://example.com/wp-json/easy-svg/v1/library?search=pfeil' \
	-u admin:'abcd efgh ijkl mnop qrst uvwx'

const term = 'pfeil';
const library = await wp.apiFetch( {
	path: `/easy-svg/v1/library?search=${ encodeURIComponent( term ) }`,
} );

library.items.forEach( ( icon ) => {
	console.log( icon.slug, icon.label );
} );

if ( library.truncated ) {
	console.warn( 'Nur die ersten 500 Icons kamen zurück. Such enger.' );
}

Außer der Anmeldung hat diese Route keinen eigenen Fehler. Für den Titel nutzt die Suche die normale Beitragssuche von WordPress, für den Slug eine eigene LIKE-Abfrage (easy_svg_icon_ids_by_slug_like()). Beide Treffermengen werden zusammengeführt, bevor die Grenze von 500 greift.

Icon hinzufügen: POST /library/add

Speichert ein Icon aus SVG-Markup. Vollständige Referenz: rest-library-add.

Ist der Slug schon vergeben, macht WordPress ihn eindeutig (aus herz wird herz-2). Die Antwort sagt es dir: added.slug ist der Slug, den das Icon bekommen hat, added.wanted der, den das Label wollte.

curl -X POST https://example.com/wp-json/easy-svg/v1/library/add \
	-u admin:'abcd efgh ijkl mnop qrst uvwx' \
	-H 'Content-Type: application/json' \
	-d '{"label":"Herz","markup":"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 21l-8-8a5 5 0 0 1 8-6 5 5 0 0 1 8 6z"/></svg>"}'

jq -n --arg label 'Herz' --rawfile markup herz.svg \
	'{label: $label, markup: $markup}' |
curl -X POST https://example.com/wp-json/easy-svg/v1/library/add \
	-u admin:'abcd efgh ijkl mnop qrst uvwx' \
	-H 'Content-Type: application/json' \
	--data-binary @-

async function myaddonAddIcon( label, markup ) {
	try {
		const result = await wp.apiFetch( {
			path: '/easy-svg/v1/library/add?_locale=user',
			method: 'POST',
			data: { label, markup },
		} );

		if ( result.added.slug !== result.added.wanted ) {
			console.info(
				`"${ result.added.wanted }" war vergeben, das Icon heißt "${ result.added.slug }".`
			);
		}
		return result.added;
	} catch ( error ) {
		// error ist der JSON-Body: { code, message, data: { status } }
		if ( 'easy_svg_add_failed' === error.code ) {
			window.alert( error.message );
			return null;
		}
		throw error;
	}
}

Jede Ablehnung durch den Speicher antwortet mit 422 easy_svg_add_failed. Nur die Meldung unterscheidet die Gründe, ein maschinenlesbares Feld für den Grund gibt es nicht. Die Prüfungen laufen in dieser Reihenfolge, und die erste, die scheitert, bestimmt die Meldung (aus easy_svg_panel_add_message(), hier im englischen Original):

Der Handler hat außerdem einen Zweig 409 easy_svg_no_store für den Fall, dass der Icon-Speicher fehlt. Er kann nicht auslösen: Er prüft function_exists( 'easy_svg_add_icon' ), und includes/icon-manager.php, wo diese Funktion steht, wird bei jeder Anfrage geladen. Bau keine Logik darauf auf.

Aus der Mediathek hinzufügen: POST /library/media

Macht aus SVG-Dateien, die schon Anhänge sind, Icons. Du schickst Anhang-IDs, nie Dateiinhalte: Der Server liest jede Datei selbst von der Platte. Vollständige Referenz: rest-library-media.

Der Titel des Anhangs wird zum Label des Icons. Jede Datei läuft durch denselben Sanitizer, dieselben Grenzen und dieselbe Härtung wie bei /library/add, denn ein SVG, das hochgeladen wurde, bevor Easy SVG aktiv war, wurde vielleicht nie bereinigt.

curl -X POST https://example.com/wp-json/easy-svg/v1/library/media \
	-u admin:'abcd efgh ijkl mnop qrst uvwx' \
	-H 'Content-Type: application/json' \
	-d '{"ids":[101,102,103]}'

// Der Server nimmt 25 IDs pro Anfrage. Mehr schickst du in Stücken, wie das Panel.
async function myaddonImportMedia( ids ) {
	const chunkSize = 25;
	const report = [];

	for ( let start = 0; start < ids.length; start += chunkSize ) {
		const result = await wp.apiFetch( {
			path: '/easy-svg/v1/library/media',
			method: 'POST',
			data: { ids: ids.slice( start, start + chunkSize ) },
		} );
		report.push( ...result.report );
	}

	return report.filter( ( row ) => 'added' !== row.state );
}

Eine Anfrage wird entweder als Ganzes abgelehnt oder antwortet 200 mit einer report-Zeile pro ID. Eine schlechte Datei hält die anderen nie auf.

Das eigene 400 easy_svg_too_many des Handlers ("Choose at most 25 files at a time.") ist über REST nicht erreichbar: maxItems im Schema lehnt eine längere Liste vorher ab. Der Zweig 409 easy_svg_no_store ist aus demselben Grund wie bei /library/add unerreichbar.

Pro Zeile ist state einer dieser Werte:

Icon umbenennen: POST /library/rename

Ändert den sichtbaren Namen und sonst nichts. Der Slug bleibt, weil Themes, Shortcodes und gespeicherte Icon-Blöcke darauf verweisen. Vollständige Referenz: rest-library-rename.

curl -X POST https://example.com/wp-json/easy-svg/v1/library/rename \
	-u admin:'abcd efgh ijkl mnop qrst uvwx' \
	-H 'Content-Type: application/json' \
	-d '{"id":42,"label":"Herz (gefüllt)"}'

const library = await wp.apiFetch( {
	path: '/easy-svg/v1/library/rename',
	method: 'POST',
	data: { id: 42, label: 'Herz (gefüllt)' },
} );

Geschrieben wird über die öffentliche Funktion easy_svg_rename_icon(). Sie schaltet kses für dieses eine Update ab (sonst würde der SVG-Inhalt für einen Administrator ohne unfiltered_html entfernt) und leert die zwischengespeicherte Icon-Liste, damit der Editor den neuen Namen sofort zeigt.

Zeichnung eines Icons ersetzen: POST /library/replace

Gibt einem vorhandenen Icon neues Markup und behält Name und Slug, damit jede Seite, die es nutzt, die neue Zeichnung zeigt. Vollständige Referenz: rest-library-replace.

jq -n --argjson id 42 --rawfile markup herz-v2.svg \
	'{id: $id, markup: $markup}' |
curl -X POST https://example.com/wp-json/easy-svg/v1/library/replace \
	-u admin:'abcd efgh ijkl mnop qrst uvwx' \
	-H 'Content-Type: application/json' \
	--data-binary @-

const library = await wp.apiFetch( {
	path: '/easy-svg/v1/library/replace',
	method: 'POST',
	data: {
		id: 42,
		markup: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M2 2h20v20H2z"/></svg>',
	},
} );

Die 422 deckt jedes andere Ergebnis von easy_svg_update_icon_markup() ab: leeres Markup, eine Ablehnung durch Sanitizer oder Grenzen, einen fehlenden Sanitizer und einen gescheiterten Datenbank-Schreibvorgang. Die Meldung spricht in all diesen Fällen von der Datei, auch wenn die Datei in Ordnung war und nur das Schreiben scheiterte.

Icon löschen: POST /library/delete

Löscht ein Icon endgültig. Vollständige Referenz: rest-library-delete.

curl -X POST https://example.com/wp-json/easy-svg/v1/library/delete \
	-u admin:'abcd efgh ijkl mnop qrst uvwx' \
	-H 'Content-Type: application/json' \
	-d '{"id":42}'

async function myaddonDeleteIcon( icon ) {
	const sure = window.confirm(
		`"${ icon.label }" löschen? Jede Seite mit easy-svg/${ icon.slug } zeigt danach nichts mehr.`
	);
	if ( ! sure ) {
		return null;
	}

	return wp.apiFetch( {
		path: '/easy-svg/v1/library/delete',
		method: 'POST',
		data: { id: icon.id },
	} );
}

Rezept: ersetzen statt einen "-2"-Zwilling anlegen

Fügst du ein Icon hinzu, dessen Name vergeben ist, bekommst du herz-2 neben herz. Wolltest du eigentlich eine neue Zeichnung für herz, bietet das Icons-Panel den Tausch an, und du kannst dasselbe mit drei Aufrufen: hinzufügen, den abweichenden Slug bemerken, das Original ersetzen und die Kopie löschen.

async function myaddonUpsertIcon( label, markup ) {
	const result = await wp.apiFetch( {
		path: '/easy-svg/v1/library/add',
		method: 'POST',
		data: { label, markup },
	} );

	const { id: newId, slug, wanted } = result.added;
	if ( slug === wanted ) {
		return result; // Der Name war frei, sonst ist nichts zu tun.
	}

	const original = result.items.find( ( icon ) => icon.slug === wanted );
	if ( ! original ) {
		return result; // Das Original liegt jenseits der ersten 500 Icons.
	}

	await wp.apiFetch( {
		path: '/easy-svg/v1/library/replace',
		method: 'POST',
		data: { id: original.id, markup },
	} );

	return wp.apiFetch( {
		path: '/easy-svg/v1/library/delete',
		method: 'POST',
		data: { id: newId },
	} );
}

Das Markup wird zweimal geprüft (beim Hinzufügen und beim Ersetzen). Das ist in Ordnung: Was beim ersten Mal durchkam, kommt auch beim zweiten Mal durch, außer der Titel des Original-Icons ergibt keinen Slug (siehe den Hinweis beim Ersetzen).

Stolperfallen

• JSON oder gar nichts. Jeder POST-Handler liest nur get_json_params(). Ohne Content-Type: application/json sind die Felder für den Handler unsichtbar, obwohl sie die Prüfung bestanden haben: /settings antwortet 200 und ändert nichts, /library/add lehnt mit "bad_name" ab, /library/rename, /library/replace und /library/delete antworten 404.
• 400 vor 401. WordPress prüft die Argumente vor der Berechtigung. Eine fehlerhafte Anfrage ohne Zugangsdaten bekommt eine 400, keine 401.
• Der Icon-Schalter sperrt die Routen nicht. Alle sieben Routen funktionieren auch bei ausgeschalteter Icon-Bibliothek. Icons, die du dann hinzufügst, sind echte esw_icon-Beiträge und tauchen auf, sobald der Schalter an ist. Die Antwort 409 easy_svg_no_store in den Handlern für add und media ist unerreichbar.
• Die zwischengespeicherte Icon-Liste kann Schreibvorgängen bei ausgeschaltetem Schalter hinterherhinken. Die Hooks, die den Cache beim Speichern und Löschen leeren (save_post_esw_icon, deleted_post), werden nur bei eingeschalteter Icon-Bibliothek registriert. /library/rename und /library/replace leeren den Cache selbst, /library/add und /library/delete nicht. Die REST-Liste betrifft das nicht (sie liest die Datenbank), aber easy_svg_icon() und der Icon-Block lesen den Cache, und der lebt bis zu einem Tag.
• Einstellungen wirken ab der nächsten Anfrage, nicht in der, die sie gespeichert hat.
• 500 Icons sind die Decke jeder Antwort. Kein Blättern. Achte auf truncated.
• Ein Fehlercode, viele Gründe. easy_svg_add_failed und easy_svg_replace_refused tragen den Grund nur in der übersetzten message. Werte sie nicht aus. Brauchst du den Grund, prüf vorher selbst oder ruf die PHP-Funktionen auf, die mit einem Zustandswort antworten.
• Labels können HTML-Entities enthalten. Bei /library/media ist das Label der Titel des Anhangs, so wie get_the_title() ihn nach den the_title-Filtern liefert (typografische Anführungszeichen werden zu ’ und Ähnlichem). Escape Labels bei der Ausgabe und vergleich sie nicht Byte für Byte mit dem, was du in der Mediathek getippt hast.
• Löschen ist endgültig. Kein Papierkorb, keine Revision, keine Warnung vor Seiten, die den Slug noch nutzen.
• Intern heißt intern. Routennamen, Felder und Codes können sich mit jedem Release ändern. Pack deine Aufrufe in eine kleine eigene Client-Funktion, dann ist eine Änderung eine einzige Korrektur.

Siehe auch

• easy-svg/v1/settings
• easy-svg/v1/library
• easy-svg/v1/library/add
• easy-svg/v1/library/media
• easy-svg/v1/library/rename
• easy-svg/v1/library/replace
• easy-svg/v1/library/delete
• easy_svg_panel_rest_permission()
• easy_svg_panel_library_payload()
• easy_svg_rename_icon()
• easy_svg_update_icon_markup()
• EASY_SVG_PANEL_LIBRARY_MAX
• EASY_SVG_MEDIA_MAX_IDS
• Ein Add-on bauen
• Entwickler-Überblick