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
This Claude skill serves as a comprehensive API protocol guide designed to standardize RESTful API development. It ensures consistency across the Sunrei project by enforcing specific naming conventions for request/response types, defining strict HTTP method rules, and providing a unified structure for success, error, and pagination responses based on OpenAPI 3.0 specifications.
Use Cases
- Standardizing API endpoint naming and structure to maintain a clean, predictable, and professional codebase.
- Defining consistent request and response types (e.g., GetUserParams, GetUserResult) to improve type safety and developer experience.
- Implementing uniform error handling and pagination formats across all project services to simplify frontend integration.
- Guiding developers on the correct application of HTTP methods (GET, POST, PUT, PATCH, DELETE) for various resource operations to ensure RESTful compliance.
- Onboarding new team members by providing a clear, executable reference for the project's architectural standards.
| 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": "..." }