# API Contracts

> Integración – contrato de API

- Skill: `jjhenao2025/api-contracts` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jjhenao2025/api-contracts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jjhenao2025/api-contracts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: jjhenao2025 (https://skillmd.com/u/jjhenao2025)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jjhenao2025/api-contracts

---


# Integración – contrato de API

**Cuándo usar:** Al crear o modificar el endpoint de rutas (`/routes`), respuestas JSON, manejo de errores o autenticación en un proyecto pybernate + ruibernate.

---

## 1. Endpoint de rutas dinámicas (`/routes`)

- El backend debe exponer un endpoint (p. ej. `GET /routes`) que devuelva un **JSON** con la estructura que espera ruiBernate. Campos principales:
  - **type:** `"route"` | `"menu"` | `"layout"`.
  - **path:** ruta (ej. `"/gm/productos"`, `"/home"`).
  - **label:** texto del menú.
  - **component:** nombre del componente (ej. `"GenericMaster"`, `"GenericMasterDetail"`, `"Home"`). Debe existir en el componentMap de routeMapper.js.
  - **icon:** nombre del icono (ej. `"ShoppingOutlined"`).
  - **insideBar:** boolean.
  - **props:** objeto; para GenericMaster/GenericMasterDetail debe incluir **`endpoint`** (ej. `"/api/productos"`).
  - **children:** array para menús anidados o layouts.
- Cada nueva entidad o pantalla que use GenericMaster o GenericMasterDetail debe quedar **reflejada en esa respuesta** (ruta y `props.endpoint` correctos) para que el frontend las muestre en el menú.
- No inventar campos ni estructuras que el frontend no espere; seguir el contrato de la guía de agentes de ruiBernate.

---

## 2. Respuestas exitosas y códigos HTTP

- **200:** OK (GET que devuelve dato(s)).
- **201:** Created (POST que crea recurso).
- **204:** No Content (DELETE exitoso, sin cuerpo).
- Cuerpo: JSON con los datos esperados (objeto o array). Estructura estable para listas (array de objetos) y paginación si el proyecto la usa.

---

## 3. Errores (cuerpo y códigos)

- Estructura fija de error en JSON, p. ej. `{ "error": "mensaje corto", "detail": "detalle opcional" }` (o la que tenga el proyecto).
- **400:** Bad Request. **404:** Not Found. **422:** Unprocessable Entity (validación Pydantic). **500:** Internal Server Error.
- En validación (Pydantic v2), devolver **422 o 400** con el detalle de los campos que fallan. No exponer trazas internas en producción.

---

## 4. Autenticación y rutas protegidas

- El backend debe exponer los endpoints que el frontend espera para auth, p. ej. `/auth/login`, `/auth/logout`, `/auth/profile`, y devolver **token** y datos de **perfil** en el formato que usa el cliente.
- El endpoint **`/routes`** debe devolver rutas **según el usuario autenticado** (permisos/rol) para que el menú dinámico muestre solo lo permitido.
- Los endpoints de datos deben **validar token o sesión** cuando corresponda; no exponer datos sensibles sin verificar autenticación.
- **No** hardcodear credenciales ni secretos en código.