The Linux Foundation Is the Home of Our API Specifications, and They Should Work Together

OpenAPI Is the Unit of API Governance

OpenAPI should be treated as the source of truth and primary unit of API governance, not a byproduct of code. Key principles include: keeping OpenAPI as the machine-readable contract everything else orbits, treating operation descriptions as high-signal governance checkpoints (a poorly described operation often signals poor design), using OpenAPI Overlays and extensions to avoid overloading the spec, and recognizing that AI agents now consume OpenAPI specs directly — making weak, under-described specs a more urgent liability than ever.

Git Is Your Governance Source of Truth

Treating API governance artifacts — OpenAPI specs, JSON Schemas, Spectral rules, and policies — as versioned code stored in Git eliminates the most common failure mode of governance: unlocatable, unversioned artifacts scattered across tools and inboxes. Git provides location certainty, full history, blame, branching, pull requests as design reviews, issues as policy backlogs, and branch protection as enforcement gates — all governance primitives that would otherwise need to be built from scratch. The GitOps approach makes the repository the single canonical source of truth, syncing outward to design tools and gateways, with the flow of authority running through the repo regardless of whether GitHub or GitLab is used.

3 REST API Testing Mistakes That Cost Us the Most Time (and How We Fixed Them)

Three common REST API testing mistakes that cause long-term maintenance pain: treating the OpenAPI spec as mere documentation instead of a source of truth, mixing contract and business assertions in the same test, and over-mocking external dependencies. The fixes involve using OpenAPI as a single canonical contract, splitting tests into contract tests (status codes, schema) and business tests (pricing, permissions, workflows), and adopting a three-layer testing strategy of unit, integration, and pre-release validation against real services. A bonus observation: authentication testing (OAuth flows, token refresh) now consumes significant CI time, with no clear industry consensus on the best approach.

Policies and Style Guides: The Why Above Your Rules

Hầu hết các chương trình quản trị API thất bại vì chỉ tập trung vào lớp thực thi (như Spectral rulesets hay lint checks) mà bỏ qua lớp chính sách (policy) giải thích lý do đằng sau quy tắc. Chính sách là tài liệu dễ đọc, mô tả "tại sao" của quy tắc, trong khi quy tắc là phiên bản máy móc ("how") để thực thi chính sách đó. Việc xây dựng chính sách giúp phát hiện những giả định ẩn và bất đồng, khiến quá trình viết tài liệu trở nên quan trọng không kém kết quả cuối cùng. Style guide đơn giản là tập hợp những chính sách này nhằm mục đích tham khảo cho con người.

Lập trình viên nên đọc bài này để hiểu cách xây dựng hệ thống quy tắc API không chỉ là kiểm tra mã mà còn là giải thích rõ ràng về mục đích kinh doanh, giúp đội ngũ phát triển và các nhà quản lý hiểu sâu hơn về ý nghĩa sau mỗi quy tắc.

Spectral Rules: Machine-Readable Enforcement

Spectral là công cụ linting mã nguồn mở mạnh mẽ cho OpenAPI, AsyncAPI và các định dạng JSON/YAML, nhưng chỉ nên coi là nền tảng cơ bản của hệ thống quản trị API. Các quy tắc hiệu quả cần đơn giản, liên kết với chính sách, có tài liệu tham khảo (documentationUrl) và mức độ nghiêm trọng (severity) được quản lý theo mức độ trưởng thành của chính sách. Ruleset cần được coi như một tài sản sống động, phát triển dần theo thời gian và bằng chứng tích lũy.

Lập trình viên nên đọc bài này để hiểu cách xây dựng và quản lý một quy tắc lọc API (Spectral) không chỉ là công cụ kiểm tra kỹ thuật mà còn là một phần cốt lõi của quy trình quản trị API hiệu quả, giúp chuyển đổi những lỗi máy tính thành hướng dẫn hành động rõ ràng và liên kết chặt chẽ với các chính sách thực tế.

JSON Schema Governs the Shape of Your Data

JSON Schema is the foundational layer beneath API contracts, where governance decisions have the highest long-term impact. Property naming conventions, data formats (timestamps, currencies, identifiers), and schema reuse via $ref are the key areas requiring strict governance. A notable insight is that both REST (OpenAPI) and async/event-driven (AsyncAPI) protocols converge at the JSON Schema layer, meaning governing data shape once covers multiple protocols. Inconsistent schemas are costly to change once consumers depend on them, making upfront discipline in naming, formats, and shared component definitions essential for coherent, maintainable APIs.

The Many Use Cases for OpenAPI Overlays

OpenAPI Overlays — a specification for applying a list of named, diffable transformations to an OpenAPI document — solve a wide range of problems beyond simple documentation edits. The official 1.0.0 release highlighted four core use cases: enriching developer experience, filtering specs for multiple audiences, localization, and injecting tool-specific metadata. Tooling implementations have converged on SDK-generation prep, public vs. internal doc splits, and batch modifications via JSONPath. Beyond these established uses, overlays are underexplored as a governance primitive: applying org-wide standards as version-controlled patches, environment promotion (rewriting servers per stage), monetization tier splits, AI/MCP agent enrichment, deprecation choreography, compliance redaction profiles, brownfield spec correction without upstream access, and generating deterministic test fixtures. The core insight is that overlays turn one-off spec edits into reusable, auditable transformations.