6.Read the Manual First

The Problem in Real Life

Trying Things Until They Work vs. Reading the Manual First

Third-Party APIs, API Documentation and OpenAPI

• Third-party APIs — specialists you rent: payments (take cards safely and legally), SMS and email (deliver messages reliably), maps, identity ("Sign in with Google", Act 22), AI, and more. You get years of a specialist's work through one API key — and you also depend on them.
• What to read before writing code: authentication (which keys, test vs live — Act 22); the main flow step by step; errors — every code and what to do about it; rate limits (how many requests per second, what happens beyond); timeouts and retries (theirs and yours); webhooks — which events, signatures, delivery rules (Friday's lesson); idempotency; versioning and how they announce changes; and sandbox/test mode details.
• Sandbox — practising on test furniture: most providers have a sandbox or test mode: fake cards, fake phone numbers, no real money or messages. Special test values trigger specific situations — a card number that always gets declined, one that triggers a bank check — so you can test failure paths, not just success.
• SDKs — the provider's own toolkit: many providers publish an SDK (a library, Act 04) that wraps their API: signature checking, retries and types already done. Using it saves mistakes — but you still need to understand the rules underneath.
• Planning for their bad days: set timeouts on every call (chapter three); decide what your app does when they're down — queue the SMS and send it later, show "your ticket will arrive by email shortly"; subscribe to their status page (a website where providers report outages); and keep a way to switch providers for critical services if one fails badly.
• API documentation — your own manual: when you are the provider, others need your manual: every endpoint, every field and type, authentication, errors, pagination, examples, and a changelog. Out-of-date docs are worse than none (Act 16).
• OpenAPI / Swagger — a manual machines can read: OpenAPI (formerly called Swagger) is a standard format — usually a YAML or JSON file — that describes an API precisely: endpoints, parameters, request and response shapes, error codes. From one OpenAPI file, tools can generate interactive documentation (try requests in the browser), client libraries in many languages, and tests that check the real API matches the description.

openapi: 3.1.0
info:
  title: BlueTicket Venue API
  version: 1.4.0
paths:
  /v1/orders:
    get:
      summary: List orders for your venue
      security: [{ oauth2: [sales:read] }]
      parameters:
        - { name: status, in: query, schema: { type: string, enum: [paid, refunded] } }
        - { name: after, in: query, description: Cursor from the previous page, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, maximum: 100, default: 100 } }
      responses:
        "200": { description: A page of orders }
        "401": { description: Missing or invalid token }
        "429": { description: Too many requests }