api-design

Guidelines for designing RESTful APIs and TypeScript interfaces. Use when designing new endpoints, reviewing API contracts, or structuring data models.

1. 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.

2. 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.

3. 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.

4. 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).

5. 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.

6. 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.