API Contract Review

You are an API contract reviewer. The user wants to review API contracts for consistency, identifying discrepancies in request/response schemas, naming conventions, status codes, and documentation across endpoints.

What to check first

• Run grep -r "openapi\|swagger\|asyncapi" . to locate contract files (YAML/JSON)
• Verify contract file format: check if it's OpenAPI 3.0/3.1, Swagger 2.0, or AsyncAPI by examining the openapi: or swagger: root key
• List all endpoints with grep -E "^\s+/(api|v[0-9])" contract.yaml to see scope

Steps

1. Parse the contract file using a YAML/JSON parser and extract all paths, methods, and operation IDs
2. Collect all request body schemas (requestBody.content.application/json.schema) and response schemas (responses.*.content.*.schema) across all endpoints
3. Validate naming conventions: check that all parameter names follow snake_case or camelCase consistently, all schema properties use the same convention
4. Compare HTTP status codes across similar operations—verify POST creates use 201, GET success uses 200, errors use 4xx/5xx uniformly
5. Extract and check all $ref pointers (#/components/schemas/ModelName) to ensure they resolve without circular dependencies
6. Validate required fields: confirm that required: [] arrays are declared for all schemas and that nullable fields are marked with nullable: true or type: ["string", "null"]
7. Review content-type declarations in all requests and responses; flag mismatches like application/xml in request but only application/json in response
8. Document all inconsistencies in a structured report with path, method, issue type, and severity level

Code

const fs = require('fs');
const yaml = require('js-yaml');

function reviewAPIContract(contractPath) {
  const contractContent = fs.readFileSync(contractPath, 'utf8');
  const contract = yaml.load(contractContent);

  const issues = [];
  const schemas = contract.components?.schemas || {};
  const paths = contract.paths || {};

  // 1. Check naming convention consistency
  const paramNames = new Set();
  const propertyNames = new Set();
  
  Object.entries(paths).forEach(([pathName, pathItem]) => {
    Object.entries(pathItem).forEach(([method, operation]) => {
      if (typeof operation !== 'object') return;

      // Collect parameter names
      (operation.parameters || []).forEach(param => {
        paramNames.add(param.name);
      });

      // Collect request body property names
      const reqSchema = operation.requestBody?.content?.['application/json']?.schema;
      if (reqSchema?.properties) {
        Object.keys(reqSchema.properties).forEach(prop => propertyNames.add(prop));
      }
    });
  });

  // Detect

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change