API Response Envelope Standardization Review Prompt

This prompt is for API designers and backend engineers who need to standardize the outer JSON wrapper across all endpoints in an API. The job-to-be-done is auditing an existing or proposed response envelope against consistency, completeness, and common anti-patterns. Use it when you are designing a new API surface, consolidating multiple internal APIs behind a gateway, or preparing for a public launch where a uniform contract reduces integration cost. The prompt assumes you have a specification snippet, an OpenAPI fragment, or a set of example response bodies to review. It does not replace a full API governance review, but it catches the structural defects that cause the most downstream consumer pain: missing request IDs, inconsistent error shapes, absent pagination metadata, and mixed envelope styles across endpoints.

The ideal user brings concrete artifacts—not abstract intentions. You need at least two endpoint response examples or an OpenAPI schema fragment showing the current state of your envelope design. The prompt works best when you provide both the proposed standard envelope and the actual endpoint responses you want to validate against it. If you only have a single endpoint, the prompt can still audit it for completeness against industry conventions, but the consistency-checking value is lost. The prompt is model-agnostic and works with any capable LLM, but you should prefer a model with strong JSON reasoning for the structured output this task requires.

Do not use this prompt when you need a full API governance review that covers business logic, authorization models, rate limiting policies, or data privacy compliance. This prompt focuses narrowly on the structural envelope—the outer JSON wrapper that every consumer must parse before reaching the domain payload. It will not catch semantic errors in your data models, incorrect HTTP status code usage, or performance problems. If you are in the early exploration phase with no concrete examples, start with the sibling API Contract Consistency Review Prompt instead. If you need to design the envelope from scratch rather than audit an existing one, pair this prompt with the API Error Response Standardization Prompt and Pagination Contract Design Prompt for a complete envelope design workflow.

This prompt template standardizes the outer response wrapper across your API endpoints. It reviews your existing or proposed envelope design against consistency rules, metadata requirements, pagination patterns, error structures, and common anti-patterns. Replace the square-bracket placeholders with your specific API context before running the review.

textCopy
You are an API design reviewer specializing in response envelope standardization. Your task is to review the provided API response envelope design and produce a structured assessment covering consistency, completeness, and anti-patterns.

## INPUT
API Specification or Endpoint Definitions:
[INPUT]

Existing API Standards or Style Guide (if any):
[CONTEXT]

## CONSTRAINTS
- Evaluate every endpoint's response wrapper for structural consistency.
- Check for required envelope fields: request ID, timestamp, status, data payload, errors, pagination metadata, and warnings.
- Flag any endpoint that deviates from the standard envelope without documented justification.
- Identify anti-patterns: inconsistent field naming, missing error envelopes, pagination metadata in the wrong location, leaking internal details, and non-standard status codes.
- If [CONTEXT] includes an existing style guide, use it as the authoritative reference. If absent, apply industry best practices (RFC 7807 for errors, common pagination conventions).
- For each finding, provide a severity rating (CRITICAL, HIGH, MEDIUM, LOW) and a concrete remediation suggestion.

## OUTPUT_SCHEMA
Return a JSON object with this structure:
{
  "summary": {
    "total_endpoints_reviewed": number,
    "compliant_endpoints": number,
    "non_compliant_endpoints": number,
    "critical_findings": number,
    "high_findings": number,
    "medium_findings": number,
    "low_findings": number
  },
  "standard_envelope": {
    "recommended_structure": "description of the recommended envelope",
    "required_fields": ["field1", "field2"],
    "optional_fields": ["field3"],
    "error_envelope": "description of error structure",
    "pagination_envelope": "description of pagination structure"
  },
  "findings": [
    {
      "endpoint": "METHOD /path",
      "severity": "CRITICAL|HIGH|MEDIUM|LOW",
      "category": "inconsistency|missing_field|anti_pattern|naming|error_handling|pagination",
      "description": "clear description of the issue",
      "current_behavior": "what the endpoint currently does",
      "expected_behavior": "what the endpoint should do",
      "remediation": "specific fix recommendation"
    }
  ],
  "consistency_matrix": {
    "field_name": {
      "present_in": ["endpoint1", "endpoint2"],
      "missing_in": ["endpoint3"],
      "inconsistent_in": []
    }
  }
}

## EXAMPLES
Example finding for a missing request ID:
{
  "endpoint": "GET /api/users",
  "severity": "HIGH",
  "category": "missing_field",
  "description": "Response envelope missing request_id field required for traceability.",
  "current_behavior": "Returns { data: [...], status: 200 } with no correlation ID.",
  "expected_behavior": "Include 'request_id' in the envelope, populated from X-Request-ID header or generated UUID.",
  "remediation": "Add request_id field to the response envelope and populate it from the incoming request context."
}

## RISK_LEVEL
[RISK_LEVEL]

If RISK_LEVEL is HIGH, flag any finding that could cause production incidents, data corruption, or security issues as CRITICAL. Require explicit human review before accepting the assessment.

## INSTRUCTIONS
1. Parse the provided API specification to identify all endpoints and their response structures.
2. Extract the envelope pattern used by each endpoint.
3. Compare each endpoint against the standard envelope defined in [CONTEXT] or against industry best practices.
4. Generate the consistency matrix showing which fields appear consistently across endpoints.
5. Produce findings for every deviation, inconsistency, or anti-pattern.
6. Assign severity based on consumer impact: CRITICAL for breaking changes or missing error handling, HIGH for inconsistency that causes integration friction, MEDIUM for style violations, LOW for cosmetic issues.
7. Return only the JSON output. Do not include explanations outside the JSON structure.

Adaptation guidance: Replace [INPUT] with your OpenAPI spec, a list of endpoint response examples, or a prose description of your API surface. Use [CONTEXT] to provide your organization's API style guide, existing envelope standards, or link to your developer portal conventions. Set [RISK_LEVEL] to HIGH if this review gates a production release or affects external consumers; use MEDIUM for internal API reviews; use LOW for exploratory design work. If your API uses a non-JSON format, adjust the OUTPUT_SCHEMA and envelope descriptions accordingly.

Validation and evals: Before trusting this review, validate the output JSON against the schema. Run the prompt against at least three endpoints you've manually reviewed to calibrate severity assignments. Common failure modes include false positives on intentionally different envelopes (e.g., health check vs. data endpoint), missed inconsistencies when endpoints use similar-but-not-identical field names, and severity inflation on cosmetic issues. For high-risk reviews, require a human to confirm every CRITICAL and HIGH finding before accepting the assessment. Log the prompt version, input spec hash, and output for auditability.

This prompt is designed to be integrated into a CI/CD pipeline or a pre-merge review workflow for API specifications. The ideal implementation treats the prompt as a stateless function: it receives an OpenAPI or protobuf specification as input and returns a structured, machine-readable JSON report. The report should be parsed by the harness to determine pass/fail status, generate annotations on a pull request, or block a deployment if critical anti-patterns are detected. The harness must manage the model call, validate the output schema, and handle retries for malformed responses before surfacing results to a human reviewer or an automated gate.

A concrete implementation in a Node.js or Python CI action would follow this sequence: (1) Load the API specification file and any existing envelope standards document. (2) Assemble the prompt by injecting the spec into the [API_SPECIFICATION] placeholder and the standards into [ENVELOPE_STANDARDS]. (3) Call a capable model (e.g., GPT-4o, Claude 3.5 Sonnet) with response_format set to json_object and a low temperature (0.1-0.2) for deterministic output. (4) Validate the returned JSON against a strict schema that requires overall_score, findings[], and recommendations[] fields. If validation fails, implement a single retry with the validation error message appended to the prompt as additional [CONSTRAINTS]. (5) Parse the validated output: if overall_score falls below a configurable threshold (e.g., 70/100) or any finding has a severity: "critical" flag, fail the CI check and post a structured comment on the PR. (6) Log the full prompt, response, and validation result to an observability platform for audit and prompt drift monitoring.

For high-risk APIs (e.g., payments, healthcare, auth), do not rely solely on the automated score. The harness should always create a human review ticket when critical findings are present. Additionally, pair this prompt with a regression test suite that includes golden examples of both compliant and non-compliant envelopes to catch model behavior changes across provider updates. Avoid wiring this prompt directly into a production deployment gate without a human-in-the-loop step for the first several runs, as the model may produce false positives for unconventional but valid design choices that your specific organizational context requires.