Skip to the content ForoHackers
Log inJoin

Diseño de API: por dónde empezar

API design
#842 · Ophuscado · · Report

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

  1. Usa tres APIs que admires y tres que no te gusten; anota en qué se diferencian.
  2. Diseña primero en papel una API HTTP pequeña: recursos, verbos, errores, paginación.
  3. Impleméntala y luego escribe un cliente solo con la documentación.
  4. Añade un cambio que no debe romper a los clientes antiguos y mira cómo lo versionas.
  5. Descríbela en una especificación legible por máquinas y genera la documentación a partir de ella.

Etiquetas relacionadas

#http #architecture #backend #documentation

Log in or join to reply.