¿Qué es una API y cómo permite integrar sistemas?

Una interfaz entre aplicaciones

API significa interfaz de programación de aplicaciones. Define operaciones disponibles, datos esperados y respuestas posibles. Un consumidor utiliza esa interfaz sin conocer tablas, lenguaje o infraestructura del proveedor. La separación permite evolucionar cada sistema mientras se respete el contrato.

Una API puede ser interna, para socios o pública. “Interna” no significa confiable por defecto: sigue necesitando autenticación, autorización, validación y seguimiento. Una API pública no implica acceso irrestricto; describe su audiencia y condiciones.

En un caso sencillo, un comercio consulta existencia en un ERP. Envía el identificador del producto a un endpoint y recibe cantidad y fecha. La API decide qué mostrar y aplica reglas del ERP. El comercio no entra directamente a sus tablas.

HTTP: solicitudes y respuestas

Muchas API empresariales utilizan HTTP, el protocolo de la web. Una solicitud combina método, dirección, encabezados y, en ocasiones, cuerpo. La respuesta incluye un código de estado, encabezados y representación. El estándar HTTP define la semántica común para que componentes distintos interpreten el intercambio.

Los métodos expresan intención. GET recupera una representación y debería ser seguro respecto al estado del recurso. POST suele crear o iniciar procesamiento. PUT reemplaza una representación conocida; PATCH aplica cambios parciales; DELETE solicita eliminar. La implementación exacta se documenta y no debe inferirse solo por el nombre.

Los códigos de estado ayudan a distinguir resultados: 2xx indica éxito; 4xx señala que la solicitud no puede atenderse bajo sus condiciones; 5xx representa una falla del servidor. Devolver 200 con un texto ambiguo de error complica monitoreo y reintentos.

Contrato, esquema y JSON

El contrato especifica rutas, parámetros, campos, tipos, reglas, ejemplos y errores. OpenAPI ofrece una especificación legible por personas y herramientas para describir API HTTP. La documentación debe mantenerse junto con el comportamiento; un ejemplo antiguo puede causar integraciones defectuosas.

JSON es un formato frecuente para datos. Representa objetos, arreglos, cadenas, números, booleanos y nulos. Que un documento sea JSON válido no significa que cumpla el contrato: un importe puede exigir moneda, precisión y rango; una fecha necesita formato y zona horaria definidos.

Los nombres deben expresar significado estable. Cambiar un campo o reutilizarlo con otra definición rompe consumidores aunque la sintaxis siga igual. Conviene decidir qué campos son obligatorios, opcionales o solo de lectura y qué ocurre con valores desconocidos.

El contrato también abarca comportamiento. ¿La creación es inmediata o asíncrona? ¿Cómo se pagina una lista? ¿Un reintento puede duplicar una orden? Las claves de idempotencia permiten reconocer solicitudes repetidas en operaciones donde el consumidor no sabe si recibió la respuesta original.

Autenticación y autorización

La autenticación identifica al consumidor; la autorización determina qué puede hacer. Una credencial válida no debería permitir consultar todos los clientes. Los permisos se evalúan por operación y recurso. En API que actúan en nombre de una persona, también se conserva su contexto autorizado.

Las credenciales se transmiten mediante canales cifrados, se almacenan como secretos y se rotan. No deben aparecer en direcciones, repositorios, ejemplos públicos ni bitácoras. Los entornos de prueba y producción usan credenciales separadas.

Toda entrada se valida en el servidor. El consumidor no controla las reglas de negocio. También se aplican límites de tamaño, frecuencia y tiempo. Los límites de frecuencia protegen capacidad y deben comunicar cómo esperar o reintentar; su valor exacto depende del servicio y del contrato. La guía OWASP API Security Top 10 llama la atención sobre autorización de objetos, autenticación, consumo de recursos, configuración e inventario, entre otros riesgos.

Errores, reintentos y observabilidad

Los errores deben ser útiles sin revelar detalles internos. Una respuesta puede incluir un código estable, mensaje seguro e identificador de correlación. El consumidor decide si corrige datos, solicita autorización o reintenta. Exponer consultas, rutas internas o rastros completos facilita ataques y no ayuda al usuario final.

Un reintento es apropiado para algunas fallas temporales, no para toda respuesta. Se usan espera creciente y límites para evitar saturar un servicio. Las operaciones no idempotentes requieren protección contra duplicados. Cuando varias acciones deben coordinarse, puede utilizarse una transacción local o una compensación explícita; no se debe asumir una transacción global.

La observabilidad conecta solicitudes mediante identificadores, métricas y trazas. Se mide latencia, volumen, estados y dependencia. Las bitácoras omiten contraseñas, tokens y datos sensibles. Una alerta debe indicar impacto y responsable, no solo que apareció una excepción.

Cambios y versiones

Una API evoluciona. Agregar un campo opcional suele ser compatible si los consumidores ignoran lo que no conocen. Eliminar, renombrar o cambiar semántica puede romperlos. Antes de un cambio se conoce quién consume la interfaz, se publica una transición y se monitorea adopción.

Las versiones pueden aparecer en ruta, encabezado u otro mecanismo. Versionar no sustituye la disciplina: mantener variantes indefinidamente eleva riesgo. Una política define soporte, avisos, fechas y retiro. Las pruebas de contrato ayudan a detectar diferencias entre documentación y servicio.

Un inventario de API, propietarios y dependencias evita interfaces olvidadas. También debe saberse dónde terminan los datos y bajo qué propósito. La documentación operativa incluye acuerdos de disponibilidad, límites y contacto para incidentes.

API, acceso a base de datos y webhook

Una API expone capacidades controladas. El acceso directo a una base permite consultas flexibles, pero acopla al esquema y puede eludir reglas. Para lectura analítica controlada puede existir una réplica o vista; para modificar operaciones suele preferirse la interfaz soportada.

Un webhook invierte la iniciativa: el proveedor notifica al consumidor cuando ocurre un evento. Reduce consultas periódicas, pero necesita firma o autenticación, reintentos, deduplicación y manejo de orden. El receptor debe responder rápido y procesar de manera segura.

Los archivos siguen siendo válidos cuando el intercambio es por lotes, la frecuencia es baja o existe un estándar establecido. Necesitan cifrado, validación, control de duplicados y confirmación. La elección no es ideológica: depende de oportunidad, volumen, consistencia y capacidades operativas.

Diseñar una integración exige identificar fuente oficial, frecuencia, identificadores y responsabilidad por errores antes de elegir tecnología. Una API elegante no salva un acuerdo de datos ambiguo.

Cómo iniciar una integración

El primer paso es describir el evento de negocio, no el endpoint. Después se acuerdan datos, responsables, volumen, oportunidad y resultado esperado. Con ese marco se selecciona el patrón técnico y se redacta el contrato.

La prueba incluye respuestas normales, datos inválidos, autorización insuficiente, lentitud, interrupción y repetición. Antes de producción se definen monitoreo, contacto, límites y recuperación. Esta preparación evita que dos equipos declaren exitosa una conexión que nadie puede operar cuando aparece la primera excepción.

Finalmente se registra la dependencia en un inventario con responsables de ambos lados. Una conexión sin propietario queda obsoleta aunque continúe respondiendo.