Awesome Reviewers

Maintain consistent patterns across all API endpoints, including naming conventions, response structures, HTTP status codes, and interface design. This ensures a predictable and professional API surface that follows established conventions.

Key consistency requirements:

• Use kebab-case (dashes) for endpoint paths, not snake_case: /end-users not /end_users, /context-variables not /context_variables
• Return appropriate HTTP status codes: 200 for updates that return data, 204 for updates without response body, 422 for semantic validation errors
• Follow consistent response patterns: create dedicated response DTOs like ReadEvaluationResponse instead of returning internal DTOs directly
• Use uniform naming across similar operations: avoid having multiple methods for identical functionality
• Maintain consistent response model specifications: either specify response_model everywhere or nowhere within the same module

Example of consistent endpoint design:

@router.patch("/{customer_id}", response_model=CustomerDTO)
async def update_customer(params: CustomerUpdateParamsDTO) -> CustomerDTO:
    # Returns 200 OK with updated entity
    
@router.get("/{evaluation_id}")  
async def get_evaluation(evaluation_id: EvaluationId) -> ReadEvaluationResponse:
    # Dedicated response DTO, not direct internal model

This prevents API fragmentation and reduces cognitive load for API consumers by establishing predictable patterns they can rely on across all endpoints.

This site is open source. Improve this page.