api-protocol

API protocol guide for Sunrei project. Use when writing API endpoints, request/response type naming, and HTTP method conventions.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

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.
nameapi-protocol
descriptionAPI 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 → create
  • PUT → full update
  • PATCH → partial update
  • DELETE → delete

Response Format

  • Success: { "data": ... } or domain key (e.g., { "sunreis": [...] })
  • Error: { "error": { "code": "...", "message": "..." } }
  • Pagination: { "items": [...], "nextToken": "..." }