RESTful APIs

Two ways into the same idea

Required Fundamentals

Core Concepts

An API is a contract between two programs: “send me a request shaped like this and I will give you a response shaped like that.” REST is a style for designing that contract on top of HTTP so it stays uniform and scalable.

1What is REST? The six constraints

Roy Fielding defined these constraints in his dissertation. An interface that respects them is called RESTful:

2Anatomy of HTTP: request and response

POST /drinks HTTP/1.1                       <- request line: method + path + version
Host: localhost:5055                        <- headers
Content-Type: application/json
Authorization: Bearer <token>
                                            <- blank line
{"name": "V60", "price_halalas": 1800}      <- body

HTTP/1.1 201 CREATED                        <- status line: version + code + reason
Content-Type: application/json
Location: /drinks/3
                                            <- blank line
{"id": 3, "name": "V60", "price_halalas": 1800}

The URL itself has parts: https://api.cafe.example:443/drinks/2?size=large#top = scheme (https) + host + port + path + query parameters (after ?) + fragment (after #, which never even reaches the server).

3HTTP vs. HTTPS

HTTPS is the same HTTP inside a channel encrypted with TLS. It gives you three things: confidentiality (intermediaries cannot read the content), integrity (nobody can alter it undetected), and server identity (a certificate proving you are talking to the right site). The default port is 80 for HTTP and 443 for HTTPS. Note that it protects the road, not the server: a badly designed API stays bad over HTTPS.

4Methods: the requested action

Safe = does not change server state. Idempotent = repeating the request several times has the same effect as once: deleting drink 2 twice leaves the same final state (although the response may change from 204 to 404). Repeating POST creates new copies, which is why clients are careful about auto-retrying it after a dropped connection.

5Status codes

6Designing resources and URLs

7Consuming an API from the command line: curl

8Consuming an API from Python: requests

9Building an API: http.server, then Flask

http.server in the standard library shows the mechanism bare: a class you inherit and write do_GET and do_POST in, composing the response by hand (send_response, then send_header, then end_headers, then writing to wfile). There is no routing, no validation and no JSON conversion, and Python’s own documentation warns that it is not recommended for production and implements only basic security checks. Flask gives you what is missing: a routing table through decorators, path converters like <int:drink_id>, jsonify, and error handlers.

Security and authentication

1️⃣1️⃣ Standards and documentation: OpenAPI

OpenAPI (formerly the Swagger Specification) is a YAML or JSON format that describes an API: paths, methods, parameters, request and response shapes, and authentication. Its strength is being readable by humans and machines alike: from the same file you can generate an interactive docs page (Swagger UI), ready-made clients, server stubs, and automatically check responses in tests.

How an API Works, Step by Step

Four pictures: the path of one request from client to server, the status-code decision tree, the difference between http.server and Flask, and the authentication ticket.

Diagram 32, The journey of a create request: the response carries 201 and the new resource’s address in Location so the client knows where to find it.

Diagram 33, The status-code decision tree: ask the questions in this order (identity, permission, input validity, resource existence) and the right code falls out automatically.

Diagram 34, The same job along two paths: in http.server you build every step, in Flask the framework builds routing and encoding and leaves you the business logic.

Diagram 35, The authentication ticket: issued once after login and sent with every later request, with no server-side session kept between requests.

Worked Example: the Coffee Menu API from Scratch

We build the coffee menu API (/drinks) and try it with all three tools. Every piece of code and output below was actually run.

Step 1, Design the resources before writing a line

Step 2, The server with Flask

from flask import Flask, jsonify, request

app = Flask(__name__)
drinks = {1: {"id": 1, "name": "Flat White", "price_halalas": 1400},
          2: {"id": 2, "name": "Cortado", "price_halalas": 1200}}
next_id = 3

@app.get("/drinks")
def list_drinks():
    return jsonify(list(drinks.values()))

@app.get("/drinks/<int:drink_id>")
def get_drink(drink_id):
    drink = drinks.get(drink_id)
    if drink is None:
        return jsonify(error="drink not found"), 404
    return jsonify(drink)

@app.post("/drinks")
def create_drink():
    global next_id
    data = request.get_json(silent=True)
    if not data or "name" not in data or not isinstance(data.get("price_halalas"), int):
        return jsonify(error="name and integer price_halalas are required"), 400
    drink = {"id": next_id, "name": data["name"], "price_halalas": data["price_halalas"]}
    drinks[next_id] = drink
    next_id += 1
    resp = jsonify(drink)
    resp.status_code = 201
    resp.headers["Location"] = f"/drinks/{drink['id']}"
    return resp

@app.delete("/drinks/<int:drink_id>")
def delete_drink(drink_id):
    if drinks.pop(drink_id, None) is None:
        return jsonify(error="drink not found"), 404
    return "", 204

if __name__ == "__main__":
    app.run(port=5055)

Step 3, Try it with curl

$ curl -i localhost:5055/drinks
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 99

[{"id":1,"name":"Flat White","price_halalas":1400},{"id":2,"name":"Cortado","price_halalas":1200}]

$ curl -i localhost:5055/drinks/99
HTTP/1.1 404 NOT FOUND
{"error":"drink not found"}

$ curl -i -X POST localhost:5055/drinks -H 'Content-Type: application/json' \
       -d '{"name":"V60","price_halalas":1800}'
HTTP/1.1 201 CREATED
Location: /drinks/3
{"id":3,"name":"V60","price_halalas":1800}

$ curl -i -X POST localhost:5055/drinks -H 'Content-Type: application/json' -d '{"name":"V60"}'
HTTP/1.1 400 BAD REQUEST
{"error":"name and integer price_halalas are required"}

$ curl -s -o /dev/null -w "%{http_code}\n" -X DELETE localhost:5055/drinks/3
204

Step 4, Consume it from Python

import requests

BASE = "http://localhost:5055"

r = requests.get(f"{BASE}/drinks", timeout=5)
print(r.status_code, r.headers["Content-Type"], r.json()[0])
# 200 application/json {'id': 1, 'name': 'Flat White', 'price_halalas': 1400}

r = requests.get(f"{BASE}/drinks/99", timeout=5)
print(r.status_code, r.json())          # 404 {'error': 'drink not found'}
try:
    r.raise_for_status()
except requests.HTTPError as e:
    print("HTTPError:", e)              # HTTPError: 404 Client Error: NOT FOUND for url: ...

r = requests.post(f"{BASE}/drinks", json={"name": "Mocha", "price_halalas": 1600}, timeout=5)
print(r.status_code, r.headers["Location"], r.json())
# 201 /drinks/3 {'id': 3, 'name': 'Mocha', 'price_halalas': 1600}

Step 5, The bare version with http.server (to see what Flask hides)

import json
from http.server import BaseHTTPRequestHandler, HTTPServer

DRINKS = [{"id": 1, "name": "Flat White"}, {"id": 2, "name": "Cortado"}]

class Handler(BaseHTTPRequestHandler):
    def _send(self, status, payload):
        body = json.dumps(payload).encode("utf-8")
        self.send_response(status)
        self.send_header("Content-Type", "application/json; charset=utf-8")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def do_GET(self):
        if self.path == "/drinks":
            self._send(200, DRINKS)
        else:
            self._send(404, {"error": "not found"})

HTTPServer(("127.0.0.1", 5056), Handler).serve_forever()

We tried it: curl -i localhost:5056/drinks returns HTTP/1.0 200 OK with Content-Type: application/json; charset=utf-8, and any other path returns 404. Notice that you wrote the encoding, the content length and every header by hand, and there is no room for POST except by reading self.rfile.read(length) yourself and validating it by hand.

Step 6, Protect deletion with a token

import hmac
from functools import wraps
from flask import request, jsonify

API_TOKEN = "..."   # in real life: from an environment variable, never from the code

def require_token(view):
    @wraps(view)
    def wrapper(*args, **kwargs):
        scheme, _, token = request.headers.get("Authorization", "").partition(" ")
        if scheme != "Bearer" or not hmac.compare_digest(token, API_TOKEN):
            return jsonify(error="authentication required"), 401, {"WWW-Authenticate": "Bearer"}
        return view(*args, **kwargs)
    return wrapper

@app.delete("/drinks/<int:drink_id>")
@require_token
def delete_drink(drink_id):
    ...

We tried it with Flask’s test client: a request with no header returns 401 with WWW-Authenticate: Bearer, a wrong token returns 401, and the correct token returns 204. Note the use of hmac.compare_digest for a constant-time comparison instead of ==.

from werkzeug.security import generate_password_hash, check_password_hash

h = generate_password_hash("correct horse")       # starts with scrypt:... and carries its salt inside
check_password_hash(h, "correct horse")            # True
check_password_hash(h, "nope")                     # False

Step 7, See what is inside a JWT (to understand why you put no secrets in it)

import base64, hashlib, hmac, json

def b64(b): return base64.urlsafe_b64encode(b).rstrip(b"=").decode()

header  = b64(json.dumps({"alg": "HS256", "typ": "JWT"}, separators=(",", ":")).encode())
payload = b64(json.dumps({"sub": "noura", "role": "barista", "exp": 1790000000}, separators=(",", ":")).encode())
sig = b64(hmac.new(b"demo-secret", f"{header}.{payload}".encode(), hashlib.sha256).digest())
token = f"{header}.{payload}.{sig}"

print(base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4)))
# b'{"sub":"noura","role":"barista","exp":1790000000}'    <- without any key!

Step 8, Document the contract with OpenAPI

One YAML file (we checked its structure parses with a YAML reader) describes the API we built. Paste it into the Swagger Editor to see the interactive docs page:

openapi: 3.0.3
info:
  title: Coffee Menu API
  version: "1.0.0"
servers:
  - url: http://localhost:5055
paths:
  /drinks:
    get:
      summary: List all drinks
      responses:
        "200":
          description: A JSON array of drinks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Drink"
    post:
      summary: Create a drink
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewDrink"
      responses:
        "201":
          description: Created
          headers:
            Location:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Drink"
        "400":
          description: Invalid input
  /drinks/{drinkId}:
    parameters:
      - name: drinkId
        in: path
        required: true
        schema:
          type: integer
    get:
      summary: Get one drink
      responses:
        "200":
          description: The drink
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Drink"
        "404":
          description: Not found
    delete:
      summary: Delete a drink
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Deleted
        "401":
          description: Missing or invalid token
        "404":
          description: Not found
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    NewDrink:
      type: object
      required: [name, price_halalas]
      properties:
        name:
          type: string
        price_halalas:
          type: integer
          minimum: 0
    Drink:
      allOf:
        - $ref: "#/components/schemas/NewDrink"
        - type: object
          properties:
            id:
              type: integer

Myth vs. Reality

Where Are APIs Used in Practice?

Try it yourself

Quick Review Flashcards

Check Your Understanding