Document API specs completely

When designing and implementing APIs, always provide comprehensive specifications that clearly document all endpoints, methods, parameters, and expected responses. This should include:

copy reviewer prompt

Prompt

Reviewer Prompt
Deploy Agent

When designing and implementing APIs, always provide comprehensive specifications that clearly document all endpoints, methods, parameters, and expected responses. This should include:

  1. Method and parameter definitions - Document each endpoint with its HTTP method, required/optional parameters, and parameter types.

Example:

PUT: /v1/storage/{tenant}/{timeline}/{endpoint}/{path}
Parameters:
- tenant: string (required) - The tenant identifier
- timeline: string (required) - The timeline identifier
- endpoint: string (required) - The endpoint identifier
- path: string (required) - The relative file path
- data: binary (required) - The file content
Response: JSON object with status and operation details

  1. Lifecycle states and transitions - For resources with complex lifecycles, document the possible states (e.g., Active, Deleted) and the API operations that trigger transitions.

  2. Service integration patterns - When an API is used for service-to-service communication, document which service is responsible for initiating specific operations and how services should interact.

  3. Error responses and handling - Include possible error codes, their meanings, and recommended client handling strategies.

Clear API specifications facilitate integration, prevent misunderstandings, and serve as essential documentation for both API producers and consumers.

Source discussions