Endpoint należy zarejestrować w namespace własnej wtyczki z jawnie określonymi metodami HTTP, argumentami, walidacją i permission callbackiem. Callback powinien wywoływać osobną usługę aplikacyjną i zwracać stabilny schemat lub ustrukturyzowany WP_Error. Proszę testować użytkownika anonimowego i uprawnionego, wartości graniczne, paginację i kompatybilność wsteczną. Dane wyjściowe warto dopuszczać za pomocą jawnego resource transformera. Wewnętrznych pól meta nie należy zwracać automatycznie.
Własny endpoint WordPress REST API udostępnia konkretną funkcję witryny aplikacji, integracji lub własnemu interfejsowi administracyjnemu. Szybki callback zwracający wynik zapytania do bazy danych może działać w pierwszym prototypie, ale bez stabilnego kontraktu klient nie potrafi rozpoznać błędu, stronicować danych ani bezpiecznie przejść na nową wersję. Implementacja staje się wtedy kruchym powiązaniem z wewnętrznymi szczegółami WordPressa.
Ten poradnik koncentruje się na projektowaniu jednego własnego endpointu – od wymagań po testy. Ogólne bezpieczeństwo i wydajność całej warstwy WordPress REST API to szerszy temat. Tutaj zajmujemy się namespace, route, schematem wejścia i wyjścia, permission callback, modelem błędów, zmianami kontraktu oraz oddzieleniem logiki aplikacji od warstwy transportowej.
Proszę zdefiniować źródło, operację i wersję route
Najpierw należy opisać operację biznesową i klienta. Odczyt listy projektów, utworzenie żądania i zmiana statusu to odrębne route’y z innymi uprawnieniami. Nazwę URL należy wyprowadzić z zasobu, używać właściwej metody HTTP oraz namespace’u z wersją, którego właścicielem jest konkretna wtyczka lub organizacja.
Kontrakt obejmuje parametry, typy, obowiązkowość, wartości domyślne, dane wyjściowe i błędy. Nie ujawniaj wewnętrznych nazw tabel ani serializowanych wartości meta tylko dlatego, że są łatwo dostępne. Model publiczny powinien pozostać stabilny także po zmianie sposobu przechowywania danych. Dokumentuj przykłady bez tokenów produkcyjnych i danych osobowych.
Proszę rejestrować argumenty i weryfikować ich znaczenie
Schema argumentu sprawdza typ, format, zakres i dozwolone wartości jeszcze przed wywołaniem callbacku. Sanityzacja doprowadza dane do bezpiecznego formatu, ale nie powinna po cichu zamieniać nieprawidłowych danych biznesowych na inną wartość. Jeśli stan jest nieznany lub data wykracza poza dozwolony okres, należy zwrócić konkretny błąd klienta ze stałym kodem.
Należy walidować również relacje między polami. Data zakończenia może wymagać daty rozpoczęcia, a pozycja musi należeć do obiektu, do którego jest dołączana. Przy zapisie proszę ponownie wczytać aktualny stan tuż przed zmianą, aby klient nie przeszedł dalej z dawno nieaktualnym założeniem. Limit rozmiaru chroni tekst, listę i przesyłane pliki.
- Typ, zakres i dozwolone wartości
- Relacje znaczeniowe między parametrami
- Limit rozmiaru żądania
- Stabilny kod błędu dla klienta
Powiąż permission callback z obiektem i akcją
Uwierzytelnianie mówi tylko, kto wywołuje żądanie. Permission callback decyduje, czy może on wykonać daną akcję na konkretnym obiekcie. Należy używać capabilities i weryfikacji własności zamiast sprawdzania nazwy roli. W przypadku listy filtr uprawnień trzeba zastosować w zapytaniu, a nie dopiero po wczytaniu i zliczeniu wszystkich rekordów.
Nonce nadaje się do żądań z zalogowanego interfejsu WordPressa, a nie jako uniwersalny klucz API dla zewnętrznego serwera. Uwierzytelnianie zewnętrzne wybierz zgodnie z obsługiwanym mechanizmem, a transport zabezpiecz za pomocą HTTPS. Odpowiedź z błędem nie powinna ujawniać, czy wrażliwy cudzy obiekt istnieje, gdy wywołujący nie ma do tego uprawnień.
Oddziel kontroler, logikę i serializację
Callback REST odczytuje zweryfikowane argumenty, wywołuje usługę aplikacyjną i serializuje wynik. Nie umieszczaj logiki biznesowej bezpośrednio w rejestracji route; wtedy nie da się jej sensownie testować ani używać z CLI czy kolejki. Usługa operuje na wartościach domenowych, a obiekty transportowe WordPressa pozostają na obrzeżach.
Dane wyjściowe tworzy jawny resource transformer, który dopuszcza tylko określone pola. Daty, waluty i liczby mają spójny format. Lista korzysta z limitu z górną granicą, stabilnej kolejności i mechanizmu paginacji. Kosztowne pola pochodne ładuj warunkowo lub buforuj w cache z precyzyjną invalidacją.
Testuj kontrakt i planuj kompatybilne zmiany
Testy automatyczne obejmą sukces, brakujący parametr, nieprawidłowy typ, wartość graniczną, użytkownika anonimowego, niewystarczające uprawnienia i cudzy obiekt. Przy zapisie testuj powtórzenie i współbieżność. Test integracyjny zweryfikuje rzeczywistą trasę, nagłówki, kody statusu i JSON, a nie tylko wewnętrzną metodę PHP.
Dodanie opcjonalnego pola jest zazwyczaj kompatybilne, zmiana znaczenia lub usunięcie już nie. Przy niekompatybilnej zmianie wydaj nową wersję route, monitoruj użycie starej i zapewnij klientom okres przejściowy. Dokumentacja i test kontraktu są aktualizowane razem z kodem. Po wdrożeniu monitoruj błędy według stabilnego kodu, a nie zawartości wrażliwych payloadów.
Najczęstsze pytania
Czy każdy endpoint REST potrzebuje permission callback?
Tak, route powinna jawnie decydować o dostępie. Publiczny endpoint może celowo zezwalać na anonimowy odczyt, ale nadal definiuje zakres i limity oraz nie może przypadkowo udostępnić niepublicznych pól.
Czy nonce to uwierzytelnianie dla aplikacji zewnętrznej?
Nonce stosuje się głównie w zalogowanej sesji WordPress i chroni konkretny kontekst żądania. Zewnętrzna aplikacja potrzebuje odpowiedniego, obsługiwanego mechanizmu uwierzytelniania, bezpiecznego transportu i ograniczonych uprawnień.
Kiedy utworzyć nową wersję REST route?
Gdy zmieniają Państwo znaczenie, pola obowiązkowe lub wynik w sposób, który może zepsuć działanie istniejącego klienta. Kompatybilne rozszerzenie można dodać do bieżącej wersji, jeśli kontrakt na to pozwala, a testy to potwierdzą.
Źródła i dalsza lektura
Adam Antoni vyvíja weby, aplikácie a softvér na mieru. Prepája firemné systémy, automatizuje procesy a vytvára AI agentov. Pôsobí v Spišskej Novej Vsi a spolupracuje s firmami na celom Slovensku.
