Saltar al contenido ForoHackers

API design: start here

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

An API is the contract by which one piece of software asks another to do something: a library's functions, a network service's endpoints, an operating system's calls. Once people depend on it, it is hard to change, so design it for the caller, keep it small, and decide early how it will evolve.

Key concepts

  • Consistency: the same names, shapes and errors everywhere, so one example teaches the rest.
  • Compatibility: adding is safe, removing or changing meaning breaks callers; version deliberately.
  • Errors as part of the contract: say what can fail, with codes and messages a program can act on.
  • Idempotence and retries: repeating a request should be safe, or clearly not.
  • Styles: resource-oriented HTTP APIs, RPC, GraphQL-style query languages and event streams suit different needs.

Vocabulary

  • Endpoint: one addressable operation or resource of a service.
  • Idempotent: doing it twice has the same effect as doing it once.
  • Pagination: returning a long result in pages with a cursor.
  • Deprecation: announcing that something will be removed, and giving time to move.

What to study, in order

  1. Use three APIs you admire and three you dislike; write down what differs.
  2. Design a small HTTP API on paper first: resources, verbs, errors, pagination.
  3. Implement it, then write a client from the documentation alone.
  4. Add a change that must not break old callers, and see how you version it.
  5. Describe it in a machine-readable specification and generate documentation from it.

Related tags

#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