Skip to main content

Context: API Gold Standard & Linting Requirements

1. Objective​

Create a Vale/Spectral linting build stage for a core platform repository to validate OpenAPI 3.0.1 specifications generated from code annotations. The goal is to move from "functional-first" documentation to a "Gold Standard" maturity model.

2. The Maturity Scorecard (Benchmark)​

All APIs must be graded against these five pillars:

  • Error Hygiene (30%): Enums must contain ONLY contextual errors (< 20 codes). Massive 1,200+ global error lists are a failure.
  • Schema Depth (20%): Strings must have format (uuid, date-time) or regex pattern.
  • Actionable Info (20%): Descriptions must explain "why/how," avoiding tautologies (e.g., "id: the id").
  • Self-Discovery (15%): Realistic JSON examples required for all request/response objects.
  • Standards Compliance (15%): Correct HTTP status codes and standard security schemes.

3. Critical Anti-Patterns to Detect​

Anti-PatternDescriptionFix Requirement
Mega-Enum ErrorsGlobal RestError with 1,000+ codes leaked into specific APIs.Filter enums to domain-specific subsets.
Insecure AuthCustomsecretkey or apikey headers.Standardize onAuthorization: Bearer and SecuritySchemes.
God ObjectsMassive resources with 5+ nested arrays (guarantors, tranches).Decompose into sub-resources (e.g.,/loans/{id}/tranches).
Tautological DocsField names repeated as descriptions.Mandate descriptive context and constraints.

4. Automation Targets for Gemini Code Assist​

  • Vale Styles: Create styles for ActionableInfo to flag words like "The ID of..." or "Represents a...".
  • Spectral Rules: (If applicable for JSON validation) Create rules to flag header parameters named secretkey or verify that every property has an example.
  • Build Stage Logic: Generate a Docker-based CI/CD step that runs these checks on every PR affecting the core platform repo.

5. Security Context​

Standardize on OAuth2/Bearer. Custom headers are designated "Insecure" due to logging leakage risks and browser/tooling incompatibility. Permission strings (x-permissions-allowed) should eventually map to OAuth2 scopes.

Last updated on