api-interface-design

API 接口设计规范，涵盖 RESTful 设计原则、URL 命名、HTTP 方法选择、请求响应格式、错误码定义、版本控制。当用户设计 API 接口、定义 Resource 类、编写接口文档或进行接口评审时使用。

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.