Skip to main content

Code Katas

Focused, repeatable design-and-defend exercises. Each kata is timed; each ends with a 2-3 sentence written defense. Repeat each kata until the time and the defense both come easily.

Format for every kata:

  • Time limit: as stated
  • Artifacts: OpenAPI YAML fragments, .proto files, or GraphQL SDL - produced as actual text, not hand-waved
  • Defense: 2-3 sentences explaining the single design decision you expect to be challenged on

Kata 1: REST API for a Given Domain with Pagination and Filtering​

Time limit: 45 minutes
Goal: Design a REST API for a small domain end-to-end.
Setup: Pick one unfamiliar domain (e.g., veterinary clinic, podcast hosting, energy grid monitoring, concert ticketing).

Produce:

  1. List of resources with justification for top-level vs nested.
  2. Full URL list for standard methods per resource.
  3. At least two custom methods with :verb URLs, bodies, responses.
  4. Pagination contract (params, response envelope, max_page_size).
  5. Filter contract (filterable fields, syntax, one example expression).
  6. Default sort with tiebreaker.
  7. Error envelope (RFC 7807-style).
  8. Idempotency rule for one non-idempotent write.

Expected size: 2 pages of OpenAPI-style YAML or Markdown.

Repeat until: you can complete it in 30 minutes on a second pass.

Kata 2: Design the Same API as gRPC and Compare​

Time limit: 40 minutes
Goal: Restate the Kata 1 API as a gRPC service, identify what moves and what stays.

Produce:

  1. One .proto file with service, all RPCs, and message definitions for 3-5 key entities.
  2. Mapping table: REST verb/URL -> gRPC method, REST status -> gRPC status for common errors.
  3. One RPC that uses streaming, with a written justification for streaming there.
  4. A 1-paragraph decision memo naming which style you would actually ship for this audience.

Repeat until: the .proto compiles in your head (no undefined types, all enums include a zero value).

Kata 3: Design the Same API as GraphQL with N+1 Mitigation​

Time limit: 40 minutes
Goal: Restate the Kata 1 API as a GraphQL schema; design for N+1 correctness.

Produce:

  1. Full GraphQL SDL: types, Query, Mutation, a connection type for pagination.
  2. Two realistic queries a client would send.
  3. A sketch of the resolver layer showing exactly where DataLoader batches are required, and which field queries trigger them.
  4. Cost/depth limit: a rule you would apply and a query that would be rejected by it.

Repeat until: you can identify every nested field that requires DataLoader in under 5 minutes.

Kata 4: Evolve v1 -> v2 with Zero-Downtime Deprecation​

Time limit: 45 minutes
Goal: Take a v1 API and evolve it to v2 using the deprecation playbook.

Setup: Invent a v1 API with 5 endpoints (or reuse Kata 1). Invent a v2 change list with at least:

  • one renamed field
  • one type-changed field (int -> object)
  • one removed endpoint
  • one new endpoint
  • one semantic change (status values, ordering, etc.)

Produce:

  1. For each change: safe or breaking, with a written rationale.
  2. For each breaking change: the migration path (new field alongside old, new endpoint alongside old, header flag, etc.).
  3. The deprecation timeline with specific dates for announce, sunset, removal.
  4. Example request/response headers at each stage.
  5. The 410 Gone response for the removed endpoint.

Repeat until: you can classify changes and produce the plan in 30 minutes, without reference.

Kata 5: Critique a Real API's Design​

Time limit: 30 minutes
Goal: Write an operational-quality critique of an existing public API.

Setup: Pick a published API (Stripe, GitHub, Linear, Spotify, PagerDuty, etc.). Read ~10 endpoints' worth of docs.

Produce a 1-page memo covering:

  1. Three things the API does well, with evidence (specific endpoint or pattern).
  2. Three things you would change, with evidence and a proposed alternative.
  3. One question you would raise in the API review council if you worked there.
  4. One thing you will copy into your own next API.

The goal is calibration, not gotcha. Stick to design decisions visible on the wire.

Repeat until: you can do it on an unfamiliar API in under 30 minutes.

Kata 6: Webhook Contract from Scratch​

Time limit: 25 minutes
Goal: Design a webhook system end-to-end.

Produce:

  1. The registration endpoint (POST /webhooks) with request and response bodies.
  2. The event envelope (headers + payload) with a worked example.
  3. The signing algorithm with the exact string to sign and the header format.
  4. The retry policy: on what responses, with what schedule, with what stop condition.
  5. The delivery contract: ordering, dedupe, retention, replay.
  6. The dashboard features a consumer needs to operate against your webhooks.

Repeat until: you can produce the whole contract in 20 minutes and defend every delivery guarantee.

Kata 7: AsyncAPI for One Event Topic​

Time limit: 20 minutes
Goal: Write a minimal but complete AsyncAPI 3.0 document for a single event channel with two message types.

Produce:

  1. info, servers, channels, operations, components/messages, components/schemas.
  2. Prose section describing delivery semantics for this channel.
  3. One breaking and one non-breaking change to a payload, with explanation.

Repeat until: the document validates in your head on the first pass.

Kata 8: API Style Guide Sprint​

Time limit: 30 minutes
Goal: Write a one-page API style guide for a hypothetical 10-team organization, then spot-check yourself by applying it to one endpoint.

Produce:

  1. Naming (case, URL pluralization, prefixes).
  2. Error format (RFC reference + stable code discipline).
  3. Pagination, filtering, sorting conventions.
  4. Timestamp and money conventions.
  5. Versioning strategy.
  6. Deprecation runway.
  7. One endpoint from an existing API of yours, audited against this guide, with fixes.

Repeat until: a colleague who has never seen the guide can apply it to a new endpoint without asking you clarifying questions.

Completion Standard​

  • All eight katas completed at least once
  • Katas 1, 4, 5 completed three or more times with different domains/APIs
  • Written artifacts (OpenAPI, .proto, GraphQL SDL, AsyncAPI) pass a linter or schema validator
  • You can explain the single design decision most likely to be challenged on every kata output
  • You have a one-page "my API style guide" you actually use