# API

## Qué es

Una API, abreviatura de interfaz de programación de aplicaciones, es el conjunto publicado de operaciones que un programa ofrece a otros programas: cómo se llama cada operación, qué acepta, qué devuelve y cómo comunica los problemas. En español escrito, la sigla no cambia en plural: las API. Quien la invoca conoce esa superficie y nada de lo que hay detrás, de modo que el programa al otro lado puede reescribirse, trasladarse a otra máquina o dividirse en tres, y quien lo llama sigue funcionando mientras se mantenga esa superficie.

La palabra abarca varias capas. La API de una biblioteca son las funciones y los tipos que exporta, a los que se llama dentro de un mismo proceso. La API de un sistema operativo es su conjunto de llamadas al sistema, y POSIX estandariza un núcleo común para que un programa escrito con `open` y `read` pueda compilarse para más de un kernel de tipo Unix. Una API web se ofrece a través de una red, casi siempre sobre HTTP, y ese es hoy el sentido habitual del término sin más: un servidor que responde a solicitudes en direcciones como `/v1/orders`, normalmente con JSON en el cuerpo.

Las API web adoptan unos pocos estilos. Las orientadas a recursos, a menudo llamadas de estilo REST, asignan una dirección a cada cosa y usan los métodos de HTTP para leerla y modificarla. Las de estilo RPC, como gRPC, publican procedimientos con nombre cuyos argumentos y resultados se declaran de antemano. GraphQL ofrece un endpoint y un sistema de tipos, y el cliente escribe una consulta que nombra exactamente los campos que quiere recibir. Los webhooks invierten la dirección: cuando ocurre algo, el proveedor llama a una dirección que el cliente había registrado.

Se confunden con ella tres términos cercanos. Un protocolo, como HTTP, define cómo viajan los mensajes; una API es lo que un servicio concreto dice mediante ese protocolo. Un SDK es una biblioteca escrita en un lenguaje de programación que envuelve la API de alguien, para que quien desarrolla llame a una función en vez de ensamblar solicitudes. La implementación, por su parte, es el código detrás de la API, que quien la invoca nunca necesita leer.

## Por qué importa

Una API es la parte de un sistema sobre la que otras personas construyen, lo que la convierte en una promesa que sobrevive al código que tiene detrás. Reescribir un manejador lleva una tarde. Cambiar lo que devuelve puede romper una app ya instalada en los teléfonos de los clientes, una importación nocturna de un socio o un script que nadie recuerda haber escrito.

La primera decisión es el público. Una API privada usada solo por el frontend del equipo puede cambiar en la misma pull request que su único cliente. Una pública cambia mediante avisos y retirada gradual; cada campo entregado deberá mantenerse mientras alguien lo lea.

La segunda decisión es el rigor del contrato. Una API estricta declara un tipo y un límite para cada entrada, rechaza lo que no reconoce y responde a cada fallo con un código de estado preciso. Detecta los errores en la entrada y resulta más fácil de documentar, probar y usar para generar clientes. Una API tolerante acepta lo que llega y hace lo que puede: parece amable el primer mes, pero después convierte cada accidente de la implementación en un comportamiento del que alguien depende. El rigor cuesta tiempo de diseño al principio; la tolerancia cuesta más después, en un momento que nadie elige.

La tercera decisión se refiere a las API ajenas. Un proveedor de pagos, un servicio de mapas o un modelo de lenguaje constituye una API que el producto invoca y no controla: cambian los precios, se retiran versiones y se reducen las cuotas. Llamar directamente a un proveedor desde cincuenta lugares convierte sustituirlo en una reescritura. Llamarlo desde un módulo que controla el propio equipo convierte la sustitución en un cambio de ese módulo. La envoltura cuesta un poco de indirección y permite disponer de una salida.

Semantic Versioning da vocabulario a esa promesa: el número de versión mayor aumenta cuando la API pública cambia de forma incompatible, de modo que un cliente puede saber solo por la versión si es seguro actualizar. Sobre HTTP hay varios lugares en los que señalar una ruptura de compatibilidad, y RFC 9205, la guía del IETF para protocolos construidos sobre HTTP, enumera entre ellos una nueva relación de enlace, un nuevo tipo de medio o un nuevo campo de cabecera.

## Cómo se aplica en la práctica

Las API de varios proyectos del sitio se diseñaron alrededor de una pregunta: qué va en la API y qué va en otro lugar.

En NextMariner, una plataforma marítima de contactos profesionales, reseñas de empresas y educación patrocinada, la contribución de la fundadora a la arquitectura incluyó mantener la API Go deliberadamente ligera. Construida con Huma sobre Fiber, enruta, valida la solicitud, aplica el filtrado de seguridad y orquesta, sin contener ninguna lógica de negocio. Las reglas residen en funciones PostgreSQL, por lo que cambiar una regla ocurre en una sola capa, en SQL. Los límites se documentaron y se hicieron cumplir en la revisión. Eso convierte a la API en un adaptador aburrido, en el buen sentido.

Un proyecto relacionado también sacó de la API la tarea de dar forma a los datos. Las funciones PostgreSQL ensamblan cada respuesta como JSON, y el manejador Go la recibe como `json.RawMessage` y la reenvía intacta mediante un pequeño auxiliar `QueryJSON`. Desaparecieron los DTO, los mapeadores y las estructuras de respuesta que suele acumular una API por capas; los manejadores se acortaron drásticamente y el frontend dejó de depender de Go. La contrapartida merece nombrarse: la forma de las respuestas de la API se define ahora en SQL, de modo que es allí donde quien revisa lee el contrato.

Una API accesible a cualquiera debe defenderse. Un directorio público de empresas y profesionales está tras 22 limitadores de frecuencia, cada uno diseñado para su ruta, con estado en Redis para aplicar el límite entre instancias. Si Redis no responde, deniegan el tráfico. Completan la defensa Cloudflare Turnstile, una restricción de origen, un desafío propio del directorio y 351 líneas de middleware de idempotencia para no duplicar una escritura reintentada. La página declara el coste: un problema de Redis se vuelve visible para el usuario, preferible a convertirlo en uno de facturación.

## Dónde surgen los problemas

Los fallos suelen aparecer tarde, cuando ya han crecido clientes y datos.

Renombrar un campo rompe un cliente desconocido. Al publicar, alguien depende de cada detalle observable: nombres, orden de listas y texto de errores. Cambiar `customer_name` por `name` rompe la integración de un socio en la siguiente solicitud. Cambie añadiendo: ponga el campo nuevo junto al antiguo, declare obsoleto este, observe los registros hasta que nadie lo lea y retírelo solo en otra versión mayor.

Un endpoint de lista se ralentiza cada mes. Devuelve todas las filas coincidentes, algo que funcionaba con cincuenta registros en el lanzamiento y que agota el tiempo de espera con doscientos mil. Incluya paginación desde la primera versión, con un tamaño de página predeterminado y un máximo estricto que el cliente no pueda superar. Para colecciones grandes o con mucha actividad, prefiera un cursor a un desplazamiento: con este último, una fila insertada entre dos solicitudes empuja otra fila a la página siguiente, donde el cliente la lee por segunda vez.

```http
GET /v1/orders?limit=50&after=ord_8f2c HTTP/1.1
Host: api.example.com
```

Un cliente lee el pedido de otro. La API comprueba la sesión y carga `/v1/orders/42` solo por identificador. Cambiar el número recorre datos ajenos. La autenticación respondió quién llama; nada preguntó si le pertenece el pedido 42. Limite cada búsqueda por propietario dentro de la consulta y mantenga una prueba que inicia sesión con una cuenta y pide registros de otra.

La respuesta expone columnas nunca destinadas a publicarse. Serializar directamente una fila o un objeto ORM envía hashes de contraseña, indicadores internos o costes de proveedor a cada cliente. Una columna añadida el próximo año se publica al crearla. En entrada, el mismo error permite fijar `role` o `is_admin` incluyéndolos en el cuerpo. Dé tipos de entrada y salida explícitos con los campos permitidos para convertir cada publicación en una decisión.

## Lecturas adicionales
* RFC 9110: HTTP Semantics — los métodos, códigos de estado y cabeceras de los que se construye toda API web, definidos por el IETF.
* RFC 9205: Building Protocols with HTTP — prácticas recomendadas actuales para diseñar una aplicación sobre HTTP, incluida su evolución.
* RFC 9457: Problem Details for HTTP APIs — una estructura JSON estándar para respuestas de error, de modo que los clientes analicen todos los fallos de la misma manera.
* RFC 6585: Additional HTTP Status Codes — donde se definen 429 Too Many Requests y su indicación `Retry-After` para clientes sujetos a límites de frecuencia.
* Semantic Versioning 2.0.0 — las reglas para señalar un cambio incompatible de API mediante un número de versión.

=> /es/portfolio/a-maritime-platform-built-in-clean-layers/ mantener la API Go deliberadamente ligera
=> /es/portfolio/designed-a-json-passthrough-from-postgres-to-api/ Las funciones PostgreSQL ensamblan cada respuesta como JSON
=> /es/portfolio/built-fail-closed-rate-limiting-and-anti-abuse/ 22 limitadores de frecuencia, cada uno diseñado para su ruta
=> https://www.rfc-editor.org/rfc/rfc9110 RFC 9110: HTTP Semantics
=> https://www.rfc-editor.org/rfc/rfc9205 RFC 9205: Building Protocols with HTTP
=> https://www.rfc-editor.org/rfc/rfc9457 RFC 9457: Problem Details for HTTP APIs
=> https://www.rfc-editor.org/rfc/rfc6585 RFC 6585: Additional HTTP Status Codes
=> https://semver.org/ Semantic Versioning 2.0.0

=> https://engineer.company/es/glossary/api/ Esta página en la web
