Api Design Reviewer

Api Design Reviewer is a community skill for evaluating REST and GraphQL API designs against best practices, covering endpoint naming conventions, request and response patterns, versioning strategies, error handling standards, and API consistency auditing.

What Is This?

Overview

Api Design Reviewer provides patterns for systematically reviewing API designs before implementation. It covers endpoint naming conventions that enforce consistent resource naming, pluralization, and URL structure, request and response patterns that validate payload structures, pagination, filtering, and content negotiation, versioning strategies that evaluate URL path, header, and query parameter approaches for API evolution, error handling standards that check error response format consistency with problem details RFC 7807, and API consistency auditing that detects deviations from established conventions across endpoints. The skill enables teams to maintain high-quality API designs.

Who Should Use This

This skill serves API architects reviewing endpoint designs before development begins, backend engineers ensuring API consistency across microservices, and technical leads establishing API standards for engineering organizations.

Why Use It?

Problems It Solves

API naming inconsistencies accumulate across teams when no automated review process exists. Error response formats vary between endpoints making client-side error handling unreliable. Pagination and filtering implementations differ across services requiring custom client logic for each API. Breaking changes are introduced without proper versioning because review processes do not catch compatibility issues.

Core Highlights

Naming analyzer checks URL patterns against RESTful conventions for resources and actions. Payload validator inspects request and response schemas for consistency. Versioning checker evaluates API evolution strategy against backward compatibility rules. Error format auditor verifies RFC 7807 compliance for error responses.

How to Use It?

Basic Usage

// API design review rules
interface ReviewRule {
  name: string;
  check: (
    spec: OpenAPISpec
  ) => ReviewResult[];
}

interface ReviewResult {
  rule: string;
  severity:
    'error' | 'warning';
  path: string;
  message: string;
}

const namingRule: ReviewRule = {
  name: 'resource-naming',
  check: (spec) => {
    const results:
      ReviewResult[] = [];
    for (const [path]
        of Object.entries(
          spec.paths)) {
      const segments = path
        .split('/')
        .filter(Boolean);

      for (const seg
          of segments) {
        if (seg.startsWith('{'))
          continue;
        if (seg !== seg
            .toLowerCase()) {
          results.push({
            rule:
              'resource-naming',
            severity: 'error',
            path,
            message:
              `Segment "${seg}"`
              + ' must be'
              + ' lowercase',
          });
        }
        if (seg.includes('_')) {
          results.push({
            rule:
              'resource-naming',
            severity: 'warning',
            path,
            message:
              'Use hyphens'
              + ' not'
              + ' underscores',
          });
        }
      }
    }
    return results;
  },
};

Real-World Examples

// Error format reviewer
const errorFormatRule:
  ReviewRule = {
  name: 'error-format',
  check: (spec) => {
    const results:
      ReviewResult[] = [];
    const required = [
      'type', 'title',
      'status', 'detail'];

    for (const [path, methods]
        of Object.entries(
          spec.paths)) {
      for (const [method, op]
          of Object.entries(
            methods)) {
        const responses =
          op.responses || {};
        for (const [code, resp]
            of Object.entries(
              responses)) {
          if (Number(code)
              >= 400) {
            const schema =
              resp?.content?.[
                'application'
                + '/json']
                ?.schema;
            if (!schema) {
              results.push({
                rule:
                  'error-format',
                severity: 'error',
                path: `${method}`
                  + ` ${path}`
                  + ` ${code}`,
                message:
                  'Error response'
                  + ' needs JSON'
                  + ' schema',
              });
            }
          }
        }
      }
    }
    return results;
  },
};

Advanced Tips

Run API design reviews as a CI check against OpenAPI specification files to catch issues before implementation. Create custom rules that enforce organization-specific conventions like required headers or authentication patterns. Use spectral or similar OpenAPI linters as a foundation and add custom rules for business-specific requirements.

When to Use It?

Use Cases

Review a new microservice API specification against team conventions before development begins. Audit existing APIs for naming and error format consistency across services. Enforce pagination standards on all list endpoints during design review.

Related Topics

API design, REST conventions, OpenAPI specification, API governance, and design review.

Important Notes

Requirements

OpenAPI 3.0 or later specification files for the API under review. Review rule definitions for naming, error format, and pagination standards. CI integration for automated design review on specification changes.

Usage Recommendations

Do: define review rules based on your team conventions and enforce them consistently across all services. Review API designs before implementation to avoid costly redesigns. Include error response format checks to ensure client developers have consistent error handling.

Don't: apply rules rigidly without considering legitimate exceptions for domain-specific requirements. Review only endpoint names while ignoring payload structure and error format consistency. Skip versioning strategy review for APIs consumed by external clients.

Limitations

Automated review cannot evaluate business logic correctness of API designs. Rule-based checking may produce false positives for intentional convention deviations. OpenAPI specifications may not capture all API behavior requiring supplementary documentation review.