Una API es el contrato con el que una pieza de software le pide a otra que haga algo: las funciones de una biblioteca, los puntos de acceso de un servicio de red, las llamadas de un sistema operativo. Cuando otros dependen de ella, es difícil de cambiar; por eso se diseña para quien la llama, se mantiene pequeña y se decide pronto cómo evolucionará.
Conceptos clave
- Coherencia: los mismos nombres, formas y errores en todas partes, para que un ejemplo enseñe el resto.
- Compatibilidad: añadir es seguro, quitar o cambiar el significado rompe a quienes la usan; versiona con intención.
- Errores como parte del contrato: di qué puede fallar, con códigos y mensajes sobre los que un programa pueda actuar.
- Idempotencia y reintentos: repetir una petición debe ser seguro, o dejar claro que no lo es.
- Estilos: las APIs HTTP orientadas a recursos, RPC, los lenguajes de consulta tipo GraphQL y los flujos de eventos sirven a necesidades distintas.
Vocabulario
- Endpoint: una operación o un recurso direccionable de un servicio.
- Idempotente: hacerlo dos veces tiene el mismo efecto que hacerlo una.
- Paginación: devolver un resultado largo en páginas con un cursor.
- Obsolescencia (deprecation): anunciar que algo se retirará, y dar tiempo para migrar.
Qué estudiar, en orden
- Usa tres APIs que admires y tres que no te gusten; anota en qué se diferencian.
- Diseña primero en papel una API HTTP pequeña: recursos, verbos, errores, paginación.
- Impleméntala y luego escribe un cliente solo con la documentación.
- Añade un cambio que no debe romper a los clientes antiguos y mira cómo lo versionas.
- Descríbela en una especificación legible por máquinas y genera la documentación a partir de ella.