api-design
Wytyczne do projektowania czystych API REST i interfejsów TypeScript
Instalacja
Wybierz klienta i sklonuj repozytorium do odpowiedniego katalogu skilli.
Instalacja
O skillu
Skill zawiera sprawdzone wzorce do projektowania spójnych API. Zastosuj go podczas tworzenia nowych endpointów, przeglądu kontraktów API lub strukturyzowania modeli danych. Dowiesz się, jak prawidłowo budować adresy URL zasobów, wybierać odpowiednie metody HTTP, zwracać właściwe kody odpowiedzi i formatować dane w odpowiedziach. Obejmuje konkretne przykłady dobrej praktyki (np. GET /users/123/orders) i błędów do uniknięcia (np. /getUsers czy /user/list).
Jak używać
Zainstaluj skill api-design z repozytorium mastra-ai w swoim projekcie. Skill jest dostępny na licencji MIT i zawiera gotowe wytyczne do zastosowania w zespole.
Kiedy projektujesz nowy endpoint, zapoznaj się z sekcją REST Endpoint Design. Upewnij się, że struktura URL podąża wzorem /{resource}, /{resource}/{id} lub /{resource}/{id}/{sub-resource}. Unikaj umieszczania czasowników w ścieżce — akcja powinna być wyrażona metodą HTTP, nie nazwą endpointu.
Wybierz właściwą metodę HTTP dla operacji: GET do odczytu, POST do tworzenia, PUT do zastąpienia całego zasobu, PATCH do aktualizacji częściowej, DELETE do usunięcia. Zwróć uwagę na idempotentność — GET, PUT i DELETE są idempotentne, POST i PATCH nie.
Zdefiniuj poprawne kody odpowiedzi HTTP. Dla sukcesu zwróć 200 (GET, PUT, PATCH z ciałem), 201 (POST) lub 204 (DELETE, PUT/PATCH bez ciała). Dla błędów klienta użyj 400 (walidacja), 401 (brak autentykacji), 403 (brak uprawnień), 404 (nie znaleziono), 409 (konflikt) lub 422 (błąd semantyczny).
Strukturyzuj odpowiedzi API zgodnie z wytycznymi formatowania. Umieść dane zasobu w polu "data", aby zapewnić spójność i ułatwić parsowanie odpowiedzi w całej aplikacji.
Przejrzyj istniejące API w zespole pod kątem zgodności z wytycznymi. Skill służy zarówno do projektowania nowych endpointów, jak i do audytu kontraktów API — użyj go jako referencji podczas code review.