---
name: api-standards
description: "Enforces Synapsis DSAI standardized API design for Flask and FastAPI, including JSON output structure, naming conventions, and status code synchronization."
tags: ["api", "json", "fastapi", "flask", "standards", "synapsis-dsai"]
---

# Synapsis DSAI API Standards Skill

Refer to: `SYN-DSAI-GL-0002` (API Output Structure)

Use this skill when developing or reviewing API endpoints to ensure they comply with the Synapsis DSAI standardized output and design patterns.

## 1. Output Format (JSON)
Every Flask/FastAPI endpoint **MUST** return the standard JSON format:

```json
{
  "status": 200,
  "message": "success",
  "data": { ... },
  "meta": { ... }
}
```

### Guidelines:
- **Backward Compatibility:** If legacy fields (e.g., `"success": true`) are required by external systems, add them redundantly at the JSON root level.
- **Implementation:** Use Pydantic models or utility helper functions to wrap all responses.

## 2. Naming Conventions
- **URL/Routes:** Always use `snake_case` (e.g., `/api/v1/get_user_profile`).
- **JSON Keys:** Always use `snake_case` (e.g., `user_id`, `created_at`).

## 3. Status Codes
- **Synchronization:** The HTTP Status Code in the response header **MUST MATCH** the `status` field in the JSON body.
- **Common Codes:**
    - `200`: Success
    - `400`: Bad Request (Validation/Client Error)
    - `404`: Not Found
    - `500`: Internal Server Error

## 4. Environment Variables
- **NO HARDCODING:** It is **STRICTLY PROHIBITED** to hardcode ports, hosts, or credentials.
- **Usage:** Always use `.env` files and environment variable loaders.

## Validation Checklist
- [ ] Does the response body match the `SYN-DSAI-GL-0002` structure?
- [ ] Is the HTTP Header status code identical to the `status` field in the body?
- [ ] Are all URL segments and JSON keys in `snake_case`?
- [ ] Are all sensitive configurations (port, host, keys) loaded from environment variables?
- [ ] Is there a Pydantic/Utility wrapper used for the response?
