relogiosoft-api-governance-kit
RelogioSoft API Governance Kit
Canonical API governance standards for designing, building, and validating consistent, secure, and evolvable REST APIs.
What is this?
The API Governance Kit is a structured corpus of 18 authoritative documents covering every dimension of REST API design. All rules use RFC 2119 language — MUST, SHOULD, MAY — so teams know exactly what is mandatory versus advisory.
It is designed to serve as:
- Human reference — browsable docs portal for engineers and reviewers
- RAG corpus — knowledge base source for the API Governance Assistant
- CI linting source — Spectral ruleset for automated OpenAPI validation
Standards overview
| # | Document | Key topics |
|---|---|---|
| 01 | API First Principles | Contract-first, API taxonomy, anti-corruption layers |
| 02 | API Lifecycle | draft → stable → deprecated → obsolete, x-status |
| 03 | API Versioning | Breaking vs non-breaking, content-type negotiation |
| 04 | URI Design | kebab-case, plural nouns, no verbs, tenant scoping |
| 05 | HTTP Verbs | GET/POST/PUT/PATCH/DELETE semantics, JSON Patch (RFC 6902) |
| 06 | HTTP Status Codes | 2xx/4xx/5xx decision flowcharts, 403 vs 404, 207 |
| 07 | Error Handling | Fault object schema, faultId, traceId, security |
| 08 | Querying & Filtering | Cursor pagination, sorting, field selection, count |
| 09 | Data Representations | ISO 8601 dates, integer money, string IDs, geospatial |
| 10 | Caching | Cache-Control, ETags, If-None-Match, If-Match |
| 11 | Observability & Logging | Structured logs, correlation IDs, GDPR, no-PII logging |
| 12 | Documentation Standards | operationId, descriptions, grammar, casing |
| 13 | Security | OAuth 2.0, CORS, TLS, OWASP Top 10, rate limiting |
| 14 | Request & Response Headers | Train-Case headers, Location, x-conversation |
| 15 | Idempotency | Idempotency-Key, deduplication, 24-hour window |
| 16 | Webhooks & Async Patterns | Delivery guarantees, HMAC signing, retries, async 202 |
| 17 | Health Endpoints | /health, /health/live, /health/ready, no-auth |
| 18 | Batch Operations | 207 Multi-Status, atomicity, max size, per-item errors |
Rule severity: MUST/MUST NOT = 🔴 Blocking · SHOULD/SHOULD NOT = 🟡 Recommendation · MAY = 🟢 Optional
Browse the docs
pip install -r requirements-docs.txt
mkdocs serve
# Open http://127.0.0.1:8000
Or browse the published portal → https://relogiosoft.github.io/relogiosoft-api-governance-kit
Lint your OpenAPI spec
npm install -g @stoplight/spectral-cli
# Against the published ruleset (no local clone needed)
spectral lint your-api.yaml \
--ruleset https://raw.githubusercontent.com/RelogioSoft/relogiosoft-api-governance-kit/main/.spectral.yml
# Against a local clone
spectral lint your-api.yaml --ruleset .spectral.yml
The Spectral ruleset covers 30+ rules across URI design, HTTP semantics, status codes, security, documentation, and data types. See docs/guides/spectral.md for the full rule reference and CI integration example.
A fully compliant example spec is at examples/openapi-example.yaml.
AI Governance Assistant
The RelogioSoft API Governance Assistant answers governance questions grounded exclusively in this corpus using AWS Bedrock Knowledge Bases. Answers include citations back to specific sections of these documents.
Repository structure
relogiosoft-api-governance-kit/
├── docs/
│ ├── index.md # Docs portal homepage
│ ├── standards/ # 18 governance standard documents
│ │ ├── 01-api-first-principles.md
│ │ └── ... (18 total)
│ └── guides/
│ ├── spectral.md # Spectral ruleset guide
│ └── contributing.md # Contribution guide
├── examples/
│ └── openapi-example.yaml # Governance-compliant example spec
├── .spectral.yml # Spectral linting ruleset
├── mkdocs.yml # MkDocs portal configuration
├── requirements-docs.txt # Python deps for local preview
└── .github/
└── workflows/
├── deploy-docs.yml # Publish to GitHub Pages on push to main
└── lint-openapi.yml # Spectral lint on every PR