Tech in Diagrams

What is an API?

An API is a documented contract that lets one piece of software ask another to do something.

Beginner 4 min IT Fundamentals
Interfaces · request and response
  • Request path
  • Response path
  • Internal calls
IMPLEMENTATION — HIDDEN FROM THE CALLERClient appMobile · web · another serviceREQUEST ENVELOPEGET /users/42Authorization: Bearer …Accept: application/jsonbody: — (POST /orders sends one)RESPONSE ENVELOPE200 OK{ "id": 42, "name": "Ada" }Shape agreed in advanceAPI CONTRACTTHE INTERFACEClients depend on this, not on what is behind it01 · ENDPOINTGET /users/{id}A named, documented address02 · AUTH & VALIDATIONVerify token, check shape401 Unauthorized · 400 Bad Request03 · ROUTINGHand off to the serviceThe caller never sees this part04 · RESPONSEStatus code + body200 OK · 404 Not FoundUser serviceApplies the rules and decides the answerDatabaseusers table · never called directlyBilling serviceAn internal call the client never sees
A request crosses the API boundary as a method, path, headers and body; the answer returns as a status code and a structured body. Everything to the right of the boundary can change without breaking the caller.

Hover a component to isolate its path; click the client, the request, any contract step, the service, the database or the response for a short explanation.

Next conceptWhat is Cloud Computing?Cloud computing is on-demand access to computing resources — servers, storage, databases and higher-level services — operated by a provider and consumed over a network.