API Quality

API Contracts

Enforce API contracts with schema validation, consumer-driven testing, and automated breaking change detection.

Schema validation

Version control

Breaking change detection

Contract Types

Schema Contracts

OpenAPI/JSON Schema validation for request/response structure

Automatic validationSelf-documentingCode generationIDE support

Consumer-Driven Contracts

Tests written by API consumers to define expectations

Consumer-first designIndependent deploymentsEarly feedbackReduced coupling

Semantic Versioning

Version numbers that communicate breaking changes

Clear expectationsSafe upgradesDeprecation pathsCompatibility tracking

Contract Testing

Automated tests that verify API contracts are maintained

CI/CD integrationBreaking change detectionRegression preventionTrust building

OpenAPI Schema Contract

Define strict schemas for requests and responses with OpenAPI 3.1 validation.

openapi/spec.yaml

# OpenAPI Schema Contract
openapi: 3.1.0
info:
  title: JustKalm API
  version: 2024-12-01
paths:
  /v1/valuations:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValuationRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Valuation'

components:
  schemas:
    ValuationRequest:
      type: object
      required:
        - brand
        - category
        - condition
      properties:
        brand:
          type: string
          minLength: 1
          maxLength: 100
          example: "Louis Vuitton"
        category:
          type: string
          enum: [bags, watches, jewelry, clothing, shoes, accessories]
        condition:
          type: string
          enum: [new, excellent, good, fair, poor]
        model:
          type: string
          description: Optional model name
        
    Valuation:
      type: object
      required:
        - id
        - object
        - estimated_value
        - confidence
        - created
      properties:
        id:
          type: string
          pattern: '^val_[a-zA-Z0-9]{24}$'
        object:
          type: string
          const: valuation
        estimated_value:
          $ref: '#/components/schemas/Money'
        confidence:
          type: number
          minimum: 0
          maximum: 1
        created:
          type: integer
          description: Unix timestamp

Best Practices

Version Everything

Pin API versions in SDKs and document upgrade paths

Additive Changes Only

Prefer adding new fields over modifying existing ones

Deprecate Gracefully

Announce deprecations 6+ months before removal

Test Consumer Contracts

Run contract tests in CI before every deploy

Document Breaking Changes

Maintain a changelog with migration guides

Use Expansion Endpoints

Add new endpoints instead of changing semantics

Ready to Enforce Contracts?

Download our OpenAPI spec and set up contract testing.

View OpenAPI Spec Browse SDKs