API Specification Schema

This guide defines the schema contract used for API specification resources so endpoint metadata stays consistent across teams and environments. It focuses on the fields you must include, recommended optional metadata, and practical validation patterns for schema quality.

Follow the core schema contract

Every specification should provide a stable identity, authentication model, and endpoint map. At minimum, include api_name, version, base_url, authentication, and endpoints so consumers can discover and validate API behavior predictably.

Optional fields such as description, rate_limits, error_codes, examples, and changelog improve usability and long-term maintenance. These fields are especially useful for client SDK generation, onboarding, and migration planning.

{
  "api_name": "platforms",
  "version": "v1",
  "base_url": "/api/v1/platforms",
  "authentication": "required",
  "endpoints": {
    "list": {
      "method": "GET",
      "path": "/",
      "summary": "List all platforms"
    }
  }
}

Apply validation rules consistently

Use predictable naming and version formats so automated tooling can verify compatibility. api_name should follow ^[a-z][a-z0-9_]*$, version should follow ^v\\d+$, and base_url should align with /api/v{n}/... path conventions.

For endpoint entries, require at least method, path, and summary. This keeps every endpoint discoverable even when deeper details such as examples and response schemas are still evolving.

type EndpointDef = { method?: string; path?: string; summary?: string };
type ApiSpec = {
  api_name?: string;
  version?: string;
  base_url?: string;
  authentication?: string;
  endpoints?: Record<string, EndpointDef>;
};

function validateSpec(spec: ApiSpec) {
  if (!spec.api_name || !/^[a-z][a-z0-9_]*$/.test(spec.api_name)) {
    return { success: false, error: { code: "INVALID_API_NAME", message: "api_name format is invalid" } };
  }
  if (!spec.version || !/^v\\d+$/.test(spec.version)) {
    return { success: false, error: { code: "INVALID_VERSION", message: "version must look like v1" } };
  }
  if (!spec.endpoints || Object.keys(spec.endpoints).length === 0) {
    return { success: false, error: { code: "MISSING_ENDPOINTS", message: "at least one endpoint is required" } };
  }
  return { success: true, data: { valid: true } };
}

Retrieve and inspect specification resources via API

Use this request flow to verify that your published API specification is discoverable and structurally valid before downstream clients depend on it.

curl -X GET "https://api.example.com/api/v1/entities?id=<ENTITY_ID>" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "entity_id": "<ENTITY_ID>",
    "name": "Example Entity",
    "status": "active"
  }
}

Keep schema evolution predictable

Use changelog and deprecation metadata whenever schema updates introduce behavior changes for existing consumers. Clear sunset timelines and migration references reduce integration risk and support controlled rollout.

Treat schema quality as part of API reliability. Well-validated specification resources improve generated documentation, reduce client errors, and make version transitions easier to manage at scale.