Skip to content

Design 0006: APIs follow the AEPs - #66

Merged
gavinbee merged 1 commit into
mainfrom
0006-aep-apis
Nov 12, 2026
Merged

gavinbee merged 1 commit into
mainfrom
0006-aep-apis

Conversation

@gavinbee

Copy link
Copy Markdown
Contributor

Refs #64 (the issue tracks the rollout this record describes, so it stays open after this merges)

What & why

Adds design 0006. swimblocks/fetch-service will be the first SwimBlocks API that other repos call, so the design rules are settled before it's written: APIs follow the AEPs.

  • Editions: keep up with current AEP editions within reason. New APIs follow the latest stable edition; when an existing API changes, adopting newer guidance is a judgement call.
  • Should rules: every AEP "should" is followed unless the design says why not.
  • Definition and linting: protobuf-first is preferred, OpenAPI-first is allowed with a reason. Every HTTP API publishes an OpenAPI 3.1 document. CI runs aep.dev's protobuf and OpenAPI linters at pinned versions.
  • Our conventions:
    • /v1/ path prefix
    • protobuf package swimblocks.<api>.v<N>
    • errors per AEP-193 (RFC 9457 problem details)
    • Cloud Run IAM between services
  • Review: an API is designed in the design record of the feature that needs it, and its definition gets the reviewer's explicit review.

Testing

Design record only. Reviewed in crit: 6 comments, all addressed.

Checklist

  • Linked the issue
  • Tests added/updated and passing (n/a, docs only)
  • ruff check . clean (n/a, docs only)
  • Docs updated (design index)

🤖 Generated with Claude Code

Refs #64

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues block the proposed API standards documentation.

No open issues 🎉

What changed in this PR

Adds proposed design 0006 to establish shared API standards before swimblocks/fetch-service becomes the first API called by other SwimBlocks repositories.

Changes:

  • Adopts AEP guidance, with stable-edition rules and documented reasons for deviations.
  • Prefers protobuf-first definitions and requires OpenAPI 3.1 publication for HTTP APIs, plus pinned CI linters.
  • Defines versioning, errors, authentication and explicit API-definition review, with rollout tracked in #64.
File Description
docs/​design/​README.md Adds design 0006 to the index as proposed.
docs/​design/​0006-aep-apis.md Documents API standards, review requirements and staged rollout.

Review effort: Balanced

@gavinbee
gavinbee merged commit f8ac546 into main Nov 12, 2026
2 checks passed
@gavinbee
gavinbee deleted the 0006-aep-apis branch November 12, 2026 19:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants