Skip to the content ForoHackers
Log inJoin

API design: start here

API design
#3347 · · Quote · Report

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

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