APIs, JSON & Contracts

In one line

An API is the menu a server offers: which requests it accepts and what it returns. Agreeing on that contract, usually HTTP + JSON, is what lets teams, apps, and services work together without reading each other's code.

0/5 · 0%

Think of it like this

A restaurant menu. You don't need to know how the kitchen works; you pick from the menu using agreed names ('Margherita, large'), and you know what you'll get. An API (Application Programming Interface) is that menu for software.

Key ideas

01
A web API endpoint is a METHOD plus a PATH: GET /products/42 (read product 42), POST /orders (create an order), DELETE /cart/items/7. The request and response bodies are usually JSON: {"id": 42, "name": "Mug", "price": 399}.
02
The response also carries a STATUS CODE: 200 OK, 201 Created, 400 Bad Request (you sent something invalid), 404 Not Found, 500 Internal Server Error (the server failed). Clients decide what to do based on it.
03
The API is a CONTRACT. Once a mobile app in users' pockets expects a field called price, renaming it to amount breaks every old app version. Good APIs change by ADDING, not by breaking, and use versioning when they must break (Phase 6B covers API design in depth).
04
Other API styles you'll meet: gRPC (fast binary calls between services), GraphQL (the client asks for exactly the fields it needs), and messages/events on a queue (asynchronous APIs). Phase 6 compares them.

Code & diagrams

an HTTP API exchangehttp

GET /products/42 HTTP/1.1
Host: api.shop.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{ "id": 42, "name": "Ceramic mug", "price": 399, "currency": "INR", "inStock": true }

Explain without notes

Why is it risky to rename a field in a public API?

Practice

Design the endpoints (method + path + example JSON) for a simple to-do app: list, create, complete, and delete tasks.

Run it in production

You've designed it. Now build, operate, and break the same idea hands-on in the DevOps courses:

Networking · HTTP on the wire

Methods, status codes, and headers in raw curl -v output.

Completion checklist

I can read an HTTP request and response
I can design simple REST endpoints for a small app

Back to phase