Skip to the content ForoHackers
Log inJoin

Diseño de API: por dónde empezar

API design
#3348 · · Quote · 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

You are not logged in, so this goes up anonymously: no account, no name and no address is stored with it, and it may carry no link and no image. Log in or join to post under your name. Our web server's logs keep the address and time of every request for up to 14 days; to keep yours out of them, use Tor. To reach the staff in confidence, use the drop. Sign as a returning source (a key kept only in this browser)

Sending takes a few seconds here: your browser first works out a proof of work against spam.

Reply