Learn APIs & Protocols — from newbie to expert

A guided path through the interfaces that connect modern software. Start with what an API and a protocol actually are, get comfortable with HTTP and REST, move into real-time push with WebSockets, server-sent events, and webhooks, meet binary RPC with gRPC — then study a working example: the REST, event, and streaming APIs GopherTrunk's own daemon exposes, and build a client against them.

Start lesson 1 →Jump to glossary

Every program you use is quietly talking to other programs — your browser to a web server, your phone’s weather app to a forecast service, GopherTrunk’s web console to the scanner daemon behind it. The rules of those conversations are APIs and protocols: agreements about who may ask what, in which format, and what the answer will look like. This module teaches you to read those agreements, use them from the command line and from code, and eventually design your own — from a first raw HTTP request all the way to binary gRPC streams.

Who this is for. Anyone who has wondered what “the API” actually is — hobbyists who want to script their scanner, web developers filling in the protocol layer beneath fetch(), and Go programmers heading toward backend work. It assumes you can run commands in a terminal; the Networking module (how bytes cross the network) and the Go programming module (the language of the code samples) are ideal companions but not prerequisites.

How the path works. Six units climb from ideas to a working client. The first is foundations — what APIs, protocols, and contracts are. The second is the workhorse: HTTP and REST, dissected one request at a time. The third covers real-time push — WebSockets, server-sent events, webhooks, and the backpressure problem behind all of them. The fourth turns to RPC and binary protocols with gRPC and Protocol Buffers. The fifth is the craft of designing and operating an API people can trust. The last unit studies a working example — the REST, event, and streaming interfaces of GopherTrunk’s own daemon — and ends with you building a client against them. Mark lessons complete as you go — your progress is saved in your browser. New here? Start with lesson 1: What is an API?

Unit 1 — API Foundations

What APIs and protocols are, who talks to whom, and the data formats requests are made of.

  1. What is an API? An API is a promise about how one piece of software may use another — the contract idea behind every interface in this module. beginner 8 min
  2. What is a protocol? Rules two parties agree on so bytes mean the same thing to both — from radio air interfaces to HTTP, it's the same idea. beginner 7 min
  3. Clients and servers Who asks and who answers — the request/response roles that shape almost every API, and where peer-to-peer differs. beginner 7 min
  4. Data formats: JSON and friends JSON, YAML, and binary encodings — how structured data is serialized so it survives the trip between programs. beginner 8 min
  5. API contracts The shape of a request and response is a promise — what breaking it costs, and why contracts outlive implementations. beginner 7 min

Unit 2 — HTTP & REST

The web's workhorse protocol and the REST conventions most APIs are built on.

  1. Anatomy of an HTTP request Method, path, headers, body, status line — dissect one request and one response and you've seen them all. beginner 9 min
  2. REST fundamentals Resources named by URLs, manipulated with a small set of verbs — the convention that makes unfamiliar APIs feel familiar. beginner 8 min
  3. Methods & status codes GET, POST, PUT, PATCH, DELETE and the status-code families — what each one promises and when to use which. beginner 8 min
  4. URLs, query strings, and bodies Where data rides in a request — path segments, query parameters, and JSON bodies, and how to choose among them. beginner 8 min
  5. API authentication API keys, tokens, and sessions — how a server knows who's calling, and why keys never belong in a URL. intermediate 9 min
  6. API versioning How APIs evolve without breaking their clients — additive change, version numbers, and deprecation done politely. intermediate 7 min

Unit 3 — Real-Time APIs

When request/response isn't enough: pushing events to clients the moment they happen.

  1. Polling vs push Asking "anything new?" every second vs being told the moment something happens — the trade at the heart of real-time design. beginner 7 min
  2. WebSockets One HTTP handshake upgrades to a persistent two-way pipe — the protocol behind live dashboards and chat. intermediate 8 min
  3. Server-sent events A one-way event stream over plain HTTP — simpler than WebSockets, and enough for most live-update needs. intermediate 8 min
  4. Webhooks The server calls you — HTTP callbacks that push events to your endpoint, and the retry and verification care they need. intermediate 8 min
  5. Streaming & backpressure What happens when the producer is faster than the consumer — buffering, dropping, and why every real stream needs a plan. advanced 9 min

Unit 4 — RPC & Binary Protocols

Calling functions across the network, and the compact binary encodings that make it fast.

  1. What is RPC? Make a network call look like a function call — the oldest idea in distributed computing, and its sharp edges. intermediate 7 min
  2. gRPC & Protocol Buffers Define messages and services in a .proto file, generate typed code, stream in both directions — RPC as practiced today. intermediate 9 min
  3. Text vs binary protocols Human-readable JSON vs compact binary framing — what each costs in bytes, speed, and debuggability. intermediate 8 min
  4. Message framing A byte stream has no natural boundaries — length prefixes, delimiters, and what goes wrong when framing drifts. advanced 8 min
  5. Schemas & code generation Write the contract once, generate the client and server from it — schemas as the single source of truth. intermediate 7 min

Unit 5 — Designing & Operating APIs

Designing interfaces people can use, and keeping them honest in production.

  1. Designing a good API Consistency, predictability, and small surface area — the qualities that make an API pleasant, and how to get them. intermediate 9 min
  2. Error handling Errors are part of the contract — status codes, machine-readable error bodies, and messages that help instead of taunt. intermediate 8 min
  3. Rate limiting & quotas Protecting a server from its own clients — limits, retry-after, and backing off like a good citizen. intermediate 7 min
  4. API documentation An undocumented API might as well not exist — reference docs, examples, and specs that stay true as code changes. beginner 7 min
  5. API security Authentication, authorization, TLS, and input validation — the checklist that keeps an exposed endpoint from becoming an incident. intermediate 9 min
  6. Testing an API Exercise endpoints with curl and Go's httptest, then pin the contract with automated tests so clients never get surprised. intermediate 8 min

Unit 6 — GopherTrunk's APIs

A working case study: the REST, event, and streaming interfaces of a real daemon — and a client of your own.

  1. GopherTrunk's REST API The daemon's HTTP API in practice — talkgroups, radio IDs, call history — and how the web console is just another client. intermediate 9 min
  2. Live events & webhooks Server-sent events and webhooks carry every call and system event out of the daemon — subscribe once, react in real time. intermediate 8 min
  3. Streaming audio with gRPC Live call audio rides a gRPC stream — the binary-RPC lessons of Unit 4 applied to real-time voice. advanced 8 min
  4. The web console's sockets Spectrum and symbol panels ride WebSockets — and GopherTrunk's own reconnect-backoff bug is a masterclass in real-time client design. advanced 9 min
  5. Build your own client Put the whole module to work — a small program that queries the REST API and follows the live event stream. advanced 10 min
  1. Glossary of API & protocol terms Plain-language definitions for every term in the module — API, endpoint, REST, HTTP method, status code, token, WebSocket, SSE, webhook, RPC, protobuf, framing, rate limit, and more — cross-linked to the lessons.