api-interface-design

Skill zawiera kompleksowe wytyczne do projektowania interfejsów API zgodnie ze standardami RESTful. Obejmuje konwencje nazewnictwa ścieżek (prefiksy /user/, /service/, /build/, /open/), wybór metod HTTP, struktury żądań i odpowiedzi, definicję kodów błędów oraz kontrolę wersji. Wykorzystaj go podczas projektowania nowych endpointów API, definiowania klas Resource, tworzenia dokumentacji interfejsów lub przeprowadzania przeglądów kodu. Zawiera gotowe przykłady w Kotlinie oraz matryce statusów HTTP i formatów błędów.

1. Zapoznaj się z konwencją ścieżek API — każdy endpoint powinien zaczynać się od prefiksu wskazującego typ dostępu: /user/ dla interfejsów dostępnych z frontendu, /service/ dla komunikacji między mikrousługami, /build/ dla agentów budowania, /open/ dla systemów zewnętrznych. 2. Przy projektowaniu nowego endpointu określ strukturę ścieżki jako /{scope}/{resource}/{resourceId}/{subResource}, gdzie scope to typ dostępu, resource to nazwa zasobu (np. pipelines), a pozostałe segmenty są opcjonalne. 3. Wybierz odpowiednią metodę HTTP (GET dla pobrania, POST dla utworzenia, PUT/PATCH dla aktualizacji, DELETE dla usunięcia) i zdefiniuj parametry — te przekazywane w nagłówkach oznacz jako @HeaderParam, w ścieżce jako @PathParam, w zapytaniu jako @QueryParam. 4. Zamodeluj odpowiedź przy użyciu generycznego formatu Result zawierającego status, message i data, lub Page dla wyników paginowanych z polami count, page, pageSize, totalPages, records. 5. Zdefiniuj kody błędów zgodnie z formatem 21(platforma)01(serwis)001(kod biznesowy), np. 2100013 dla błędu parametru — dokumentuj każdy kod w specyfikacji interfejsu. 6. Przejrzyj przykład implementacji w Kotlinie zawartej w skill — zawiera dekoratory @Tag, @Path, @GET/@POST, @Parameter oraz poprawne mapowanie parametrów do metody.