Saltar al contenido ForoHackers

API design: start here

Diseño de API
#841 · Ophuscado · · 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

Inicia sesión o únete para responder.