Desarrollo · Integración · 9 min de lectura

APIs REST: contratos que no te traicionan

En software a medida, la API es el contrato con el mundo exterior: apps móviles, partners, RPA y a veces SUNAT vía intermediarios. Si el contrato es vago, el mantenimiento explota.

Recursos y verbos coherentes

Nombres de recursos en plural, IDs estables, GET idempotente, POST para crear, PATCH para cambios parciales cuando aplica. Evitar sobrecargar un mismo endpoint con “modo” por query string si genera ambigüedad.

Errores legibles por máquina y por humano

Código HTTP correcto (4xx cliente, 5xx servidor), cuerpo JSON con code, message y, si aplica, field. El front y los robots RPA pueden reaccionar sin parsear texto libre.

Versionado

/v1/ en la ruta o cabecera Accept con vendor media type: lo importante es documentar y no romper clientes existentes. Cambios incompatibles → nueva versión; deprecación con plazo.

OpenAPI (Swagger)

Un OpenAPI mantenido es el mejor seguro contra “teléfono descompuesto” entre equipos. Genera mocks, pruebas contractuales y handoff claro con terceros.