API: cómo el software habla con el software
Una API es una promesa: envía una petición con esta forma y recibe un resultado con aquella forma. Es el contrato que permite a dos sistemas cooperar sin conocer las entrañas del otro.
Una API es una promesa: pides con la forma acordada, recibes una respuesta con la forma acordada, y nunca ves la maquinaria que hay detrás. La forma más rápida de entender una es leer un intercambio real.
Al terminar esta lección
Serás capaz de leer una petición y una respuesta HTTP, nombrar los cuatro verbos que hacen funcionar la web, y saber qué es OpenAPI y por qué es el puente silencioso de las API hacia la IA.
Si la línea de comandos es la puerta para las personas, la API —interfaz de programación de aplicaciones— es la puerta para el software. Un programa le pide a otro que haga algo, y la idea clave es que no necesitas saber cómo funciona por dentro el otro sistema. Solo honras su contrato: envías una petición con la forma acordada, recibes una respuesta con la forma acordada. Las entrañas permanecen ocultas, que es justamente lo que permite a dos equipos, o a dos empresas, cooperar sin coordinar cada detalle.
Aquí tienes un intercambio real: un programa pidiéndole a un servicio meteorológico la temperatura en Lima, y el servicio respondiendo. Unas pocas líneas en cada dirección, cada parte cumpliendo una sola función.
Esa palabra del principio —GET— y el número que vuelve —200— son las dos cosas que vale la pena entender. Empieza por el verbo.
REST: el estilo que hace funcionar la web
La mayoría de las API que te encontrarás siguen REST, un estilo arquitectónico que Roy Fielding definió en su tesis doctoral de 2000 — y él fue coautor de las propias especificaciones de HTTP, así que no se trata de un advenedizo teorizando. La jugada de REST es elegante: en lugar de inventar verbos nuevos, reutiliza los cuatro que HTTP ya tiene.
Así, GET /posts lee entradas, POST /posts crea una, DELETE /posts/42 elimina una. Una vez que interiorizas este patrón, puedes adivinar cómo funcionan la mayoría de las API web antes de leer una sola línea de su documentación — ese es el poder de un estilo compartido. El 200 de antes forma parte del mismo acuerdo: una pequeña familia de códigos de estado (200 funcionó, 404 no encontrado, 500 error del servidor) que toda API comparte.
Poner el contrato por escrito: OpenAPI
Si una API es un contrato, OpenAPI es ese contrato escrito en un archivo legible por máquina. Empezó como “Swagger” en 2011 y se convirtió en la OpenAPI Specification bajo la Linux Foundation en 2016. Ese archivo es lo que permite a las herramientas autogenerar documentación y código de cliente — y, cada vez más, lo que permite a una IA entender una API sin que un humano se la explique. Quédate con esta idea: una descripción legible por máquina de lo que un sistema puede hacer, y de cómo invocarlo, es exactamente el puente hacia la siguiente puerta de este curso.
Aprende la forma una vez, y toda API te resultará familiar.
Prueba esto
La próxima vez que una app haga algo a través de internet —carga tu feed, envía un mensaje, obtiene un precio—, imagina la petición que hay detrás. ¿Qué verbo? ¿Cuál es la ruta? ¿Qué vuelve? Empezarás a ver la web como un intercambio constante de estos pequeños contratos, que es exactamente lo que es.
Basado en Roy Fielding, REST dissertation (2000); Wikipedia, REST y OpenAPI Specification.
0
Toca para valorar
¿Te resultó útil este capítulo?