Index of every page on this site: llms.txt
All skills
jeremylongshore avatar

/validating-api-responses

@820dfc8
Run it yourself

Validate API responses against schemas to ensure contract compliance and data integrity. Use when ensuring API response correctness. Trigger with phrases like "validate responses", "check API responses", or "verify response format".

Use this Skill: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/validating-api-responses

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesexamples.md

≈1.5k tokens on demand. Your agent reads this file only when SKILL.md points to it.

API Response Validation Examples

Response Validation Middleware (Ajv)

const Ajv = require('ajv');
const addFormats = require('ajv-formats');
const ajv = new Ajv({ allErrors: true, strict: false });
addFormats(ajv);

function responseValidator(schemaMap) {
  return (req, res, next) => {
    const orig = res.json.bind(res);
    res.json = (body) => {
      const key = `${req.method}:${req.route?.path}:${res.statusCode}`;
      const schema = schemaMap[key];
      if (schema) {
        const validate = ajv.compile(schema);
        if (!validate(body)) {
          const isStrict = process.env.NODE_ENV !== 'production';
          logger.warn({ path: key, errors: validate.errors }, 'Response validation failed');
          responseValidationFailures.inc({ path: req.route?.path, status: res.statusCode });
          if (isStrict) {
            return orig({ title: 'Response Validation Error', errors: validate.errors });
          }
        }
      }
      return orig(body);
    };
    next();
  };
}

Schema Map from OpenAPI

// validators/compile-schemas.js
const yaml = require('js-yaml');
const fs = require('fs');

function compileSchemas(specPath) {
  const spec = yaml.load(fs.readFileSync(specPath));
  const schemaMap = {};

  for (const [path, methods] of Object.entries(spec.paths)) {
    for (const [method, operation] of Object.entries(methods)) {
      for (const [statusCode, response] of Object.entries(operation.responses || {})) {
        const schema = response?.content?.['application/json']?.schema;
        if (schema) {
          const key = `${method.toUpperCase()}:${path}:${statusCode}`;
          schemaMap[key] = resolveRefs(schema, spec.components?.schemas || {});
        }
      }
    }
  }
  return schemaMap;
}

const schemas = compileSchemas('./openapi.yaml');
app.use(responseValidator(schemas));

User Response Schema

{
  "type": "object",
  "required": ["id", "name", "email", "status", "createdAt"],
  "additionalProperties": false,
  "properties": {
    "id": { "type": "string", "pattern": "^usr_[a-zA-Z0-9]+$" },
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "status": { "type": "string", "enum": ["active", "inactive", "suspended"] },
    "createdAt": { "type": "string", "format": "date-time" }
  }
}

Contract Test Suite

describe('Response Contract Tests', () => {
  it('GET /users returns valid paginated list', async () => {
    const res = await request(app).get('/users?page=1&limit=5');
    expect(res.status).toBe(200);

    const { data, pagination } = res.body;
    expect(Array.isArray(data)).toBe(true);
    for (const user of data) {
      expect(user.id).toMatch(/^usr_/);
      expect(typeof user.name).toBe('string');
      expect(user.email).toMatch(/@/);
      expect(['active', 'inactive', 'suspended']).toContain(user.status);
      expect(new Date(user.createdAt).toISOString()).toBe(user.createdAt);
    }
    expect(pagination).toMatchObject({ page: 1, limit: 5 });
    expect(typeof pagination.total).toBe('number');
  });

  it('GET /users/:id returns valid user', async () => {
    const res = await request(app).get('/users/usr_test1');
    expect(res.status).toBe(200);
    expect(res.body).not.toHaveProperty('passwordHash');
    expect(res.body).toHaveProperty('id');
    expect(res.body).toHaveProperty('email');
  });

  it('POST /users returns 400 with field errors', async () => {
    const res = await request(app).post('/users')
      .send({ name: '', email: 'invalid' });
    expect(res.status).toBe(400);
    expect(res.body.errors).toBeDefined();
    expect(res.body.errors.length).toBeGreaterThan(0);
    for (const err of res.body.errors) {
      expect(err).toHaveProperty('field');
      expect(err).toHaveProperty('message');
    }
  });

  it('GET /users/nonexistent returns 404 RFC 7807', async () => {
    const res = await request(app).get('/users/nonexistent');
    expect(res.status).toBe(404);
    expect(res.body).toHaveProperty('type');
    expect(res.body).toHaveProperty('title');
    expect(res.body).toHaveProperty('status', 404);
  });
});

Schema Drift Detection

async function detectSchemaDrift(endpoint, schema) {
  const res = await fetch(`http://localhost:3000${endpoint}`);
  const body = await res.json();
  const actual = inferSchema(body);
  const diff = compareSchemas(schema, actual);

  if (diff.addedFields.length > 0) {
    logger.warn({ endpoint, fields: diff.addedFields }, 'Undocumented fields in response');
  }
  if (diff.removedFields.length > 0) {
    logger.error({ endpoint, fields: diff.removedFields }, 'Missing documented fields');
  }
  return diff;
}

Backward Compatibility Check

function checkBackwardCompatibility(v1Schema, v2Schema) {
  const issues = [];

  for (const field of v1Schema.required || []) {
    if (!v2Schema.properties?.[field]) {
      issues.push({ type: 'REMOVED_FIELD', field, severity: 'breaking' });
    }
  }

  for (const [field, v1Type] of Object.entries(v1Schema.properties || {})) {
    const v2Type = v2Schema.properties?.[field];
    if (v2Type && v1Type.type !== v2Type.type) {
      issues.push({ type: 'TYPE_CHANGED', field, from: v1Type.type, to: v2Type.type, severity: 'breaking' });
    }
  }

  return { compatible: issues.filter(i => i.severity === 'breaking').length === 0, issues };
}

Production Sampling

function sampledValidator(schemaMap, sampleRate = 0.05) {
  return (req, res, next) => {
    if (Math.random() > sampleRate) return next();
    return responseValidator(schemaMap)(req, res, next);
  };
}
app.use(sampledValidator(schemas, 0.05)); // Validate 5% of responses

Tons of Skills by Intent Solutions | jeremylongshore.com

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo3 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill provides a comprehensive framework for validating API responses against OpenAPI and JSON schemas. It utilizes industry-standard tools and patterns for ensuring data integrity and contract compliance in development and production environments.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

Signed by skilld at 820dfc8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last month
What it can do
Reads files Edits files Runs commands
version
1.25.0
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
[
  "api",
  "compliance",
  "validating-api"
]
All 6 allowed tools
ReadWriteEditGrepGlobBash(api:validate-*)
Other metadata
compatibility
Designed for Claude Code

README badge

README badge for jeremylongshore/tons-of-skills-marketplace/validating-api-responses