Skip to content
Thymian

Use linting to validate your APIs

The HTTP plugins (@thymian/plugin-http-linter, @thymian/plugin-http-tester and @thymian/plugin-http-analyzer) enable you to validate HTTP APIs at every stage of development—from design and implementation to testing and production monitoring. Write validation rules once and apply them across static specifications, live API tests, and recorded traffic analysis.

Why HTTP Linting?

Section titled “Why HTTP Linting?”

Modern API development faces several challenges:

  • API drift between specification and implementation
  • Inconsistent behavior across endpoints and versions
  • Compliance issues with HTTP standards or internal guidelines
  • Breaking changes that affect clients

HTTP linting addresses these challenges by providing automated validation that runs throughout your development lifecycle.

Key Features

Section titled “Key Features”
  • Write once, validate everywhere — Rules work across static specs, live tests, and traffic analysis
  • Powerful filter DSL — Declaratively match HTTP requests and responses
  • Type-safe — Full TypeScript support with IDE autocomplete
  • Extensible — Create and share custom rule sets as npm packages
  • CLI tools — Generate, search, and manage rules from the command line

Quick Start

Section titled “Quick Start”

Here’s a simple custom rule that enforces API versioning across your organization:

import { httpRule, not, constant } from '@thymian/core';


export default httpRule('api-must-include-version-in-path')
  .severity('error')
  .type('static', 'analytics')
  .description('All API endpoints must include /v{number}/ in path for versioning')
  .appliesTo('server')
  .rule((ctx) => ctx.validateCommonHttpTransactions(constant(true), (req) => /api\/v\d+/.test(req.path)))
  .done();

This custom organizational rule automatically validates:

  • Lint — Checks OpenAPI definitions during design
  • Analyze — Validates recorded HTTP transactions from production

Use Cases

Section titled “Use Cases”

Prevent API Drift

Section titled “Prevent API Drift”

Validate that your running API matches its specification by applying the same rules to both:

// Rule validates both spec and implementation
.type('static', 'test')

Enforce API Governance

Section titled “Enforce API Governance”

Create organization-wide rules for consistent API behavior:

// Ensure all authenticated endpoints include rate limit headers
httpRule('authenticated-endpoints-must-include-rate-limits')
  .type('analytics', 'test')
  .rule((ctx) => ctx.validateCommonHttpTransactions(and(authorization(), successfulStatusCode()), not(responseHeader('x-ratelimit-remaining'))))
  .done();

Validate Production Traffic

Section titled “Validate Production Traffic”

Analyze recorded traffic to detect issues in production:

// Analyze-only rule for production monitoring
.type('analytics')

How It Works

Section titled “How It Works”
graph LR
    A[HTTP Rule] --> B[Lint Context]
    A --> C[Test Context]
    A --> D[Analyze Context]

    B --> E[Validates OpenAPI Spec]
    C --> F[Generates & Runs Tests]
    D --> G[Analyzes Recorded Traffic]

    E --> H[Reports Violations]
    F --> H
    G --> H

The HTTP linter provides three validation contexts, each suited for different stages of development:

  1. Lint — Fast validation against API specifications
  2. Test — Active testing of live endpoints
  3. Analyze — Passive analysis of recorded HTTP traffic

Rules can target one or more contexts, and the linter automatically adapts the validation logic to each context.

Documentation

Section titled “Documentation”
  1. What is an HTTP Rule? — Core concepts and rule anatomy
  2. Creating New Rules — Step-by-step guide to writing rules
  3. Rule Types — Understanding static, test, and analytics contexts
  4. Combining Different Rule Types — Writing hybrid rules
  5. How To Use Rules — Integration and configuration
  6. CLI — Command-line tools reference

Next Steps

Section titled “Next Steps”