<!--
title: API consistency standards
domain: ai-agents
topic: API
language: Python
source: emcie-co/parlant
updated: 2025-09-14
url: https://awesomereviewers.com/reviewers/parlant-api-consistency-standards/
-->

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:
```python
@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.
