Saltar al contenido ForoHackers

Diseño de API: por dónde empezar

Diseño de API
#3348 · · Citar · Denunciar

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

No has iniciado sesión, así que esto se publica como anónimo: no se guarda con ello ninguna cuenta, nombre ni dirección, y no puede llevar enlaces ni imágenes. Inicia sesión o únete para publicar con tu nombre. Los registros de nuestro servidor web guardan la dirección y la hora de cada petición hasta 14 días; para que la tuya no quede en ellos, usa Tor. Para escribir al equipo de forma confidencial, usa el buzón. Firmar como fuente habitual (una clave guardada solo en este navegador)

Enviar tarda unos segundos aquí: tu navegador resuelve antes una prueba de trabajo contra el spam.

Responder