Beginner System Architecture

What Is an API

API stands for Application Programming Interface. It is a contract that lets one piece of software talk to another. You do not need to know how the other system works inside; you only need to know what to send and what you get back. A good API hides complexity behind a clear agreement.

A contract, not the implementation

Think of a restaurant. The menu is the API: it lists what you can order and what you will receive. You do not enter the kitchen. The menu shields you from the cooking details and lets the kitchen change recipes freely.

You (client)  --- order from menu --->  Kitchen (server)
You (client)  <--- dish delivered  ----  Kitchen (server)
   The menu = the API contract

Why APIs matter

  • They let teams and systems work independently.
  • They allow reuse: many clients can call the same API.
  • They hide internal changes, as long as the contract holds.
  • They enable integration between companies and services.

A request and response

Most web APIs exchange structured messages. Here is a typical HTTP call.

GET /v1/users/42 HTTP/1.1
Host: api.example.com
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json

{ "id": 42, "name": "Ada", "active": true }

Common types of API

  • REST: resources over HTTP, the most common style for web services.
  • GraphQL: the client asks for exactly the fields it needs in one query.
  • gRPC: fast binary calls between services, great for internal microservices.
  • WebSocket: a persistent, two-way connection for real-time updates.
  • SOAP: an older XML-based standard, still found in enterprise systems.
  • Library/SDK APIs: functions you call inside your own code, no network.
Style     Transport    Best for
REST      HTTP/JSON    public web services, CRUD
GraphQL   HTTP/JSON    flexible client-driven reads
gRPC      HTTP/2       fast internal service-to-service
WebSocket TCP          real-time, bidirectional

Picking one

Start with REST for most public web services because it is simple and widely understood. Choose GraphQL when clients need flexible queries, gRPC for high-performance internal traffic, and WebSocket when you need live updates. The right choice depends on who calls the API and how often.