MEPX
Chapter 1 of 10All chapters
  1. 1What an API is
  2. 2The request
  3. 3The response
  4. 4REST and its alternatives
  5. 5Authentication
  6. 6JSON and data shapes
  7. 7Pagination and filtering
  8. 8Rate limits and retries
  9. 9Versioning and change
  10. 10Calling and debugging APIs

Chapter 1 of 10

What an API is

A contract, not a technology.

The contract

An API defines what one program can ask another to do: the operations, the inputs, the outputs and the errors. Everything else is implementation the caller should not need to know.

  • A good API hides how the work is done and keeps its promises stable.
  • Every published endpoint is a commitment you have to keep working.

Web APIs

Most APIs today are HTTP endpoints exchanging JSON, because that works from any language and passes through ordinary web infrastructure.