api-protocol
API protocol guide for Sunrei project. Use when writing API endpoints, request/response type naming, and HTTP method conventions.
When & Why to Use This Skill
The api-protocol skill serves as a comprehensive API design and standardization guide for the Sunrei project. It enforces RESTful best practices and OpenAPI 3.0 specifications, ensuring consistency across endpoint naming, HTTP method usage, and request/response structures. By providing clear conventions for parameters and results, it helps developers maintain a clean, predictable, and scalable API architecture while reducing integration friction.
Use Cases
- Endpoint Design: Use the guide to define the correct HTTP methods and URL paths for resources, such as using GET for retrieval and POST for creation according to project standards.
- Type Naming Consistency: Standardize the naming of request and response objects (e.g., GetUserParams and GetUserResult) to ensure the codebase remains intuitive and maintainable.
- Standardized Error Handling: Implement uniform error response formats across all services to simplify client-side error processing and debugging.
- Pagination Implementation: Apply the predefined pagination structure using 'items' and 'nextToken' to ensure consistent data fetching behavior across different list endpoints.
| name | api-protocol |
|---|---|
| description | API protocol guide for Sunrei project. Use when writing API endpoints, request/response type naming, and HTTP method conventions. |
API Protocol Guide
RESTful API + OpenAPI 3.0 spec
- Request type:
{HttpMethod}{Name}Params(e.g.,GetUserParams,ListUsersParams) - Response type:
{HttpMethod}{Name}Result(e.g.,GetUserResult,ListUsersResult)
HTTP Method Rules
GET+ singular → single item (e.g.,GET /sunreis/{id})List+ plural → list items (e.g.,GET /sunreis)POST→ createPUT→ full updatePATCH→ partial updateDELETE→ delete
Response Format
- Success:
{ "data": ... }or domain key (e.g.,{ "sunreis": [...] }) - Error:
{ "error": { "code": "...", "message": "..." } } - Pagination:
{ "items": [...], "nextToken": "..." }