---
name: python-rest-api-validator
description: "A runnable Python script that calls one endpoint and fails loudly if the status code, required headers, or JSON shape differ from what you expect, ready to drop into CI or a post-deploy smoke test. Use when an endpoint's status code, headers, and JSON body need an automated check that can run in CI or as a smoke test after each deploy. Do not use for load testing, full contract test suites across many endpoints, or mocking an API. Related topics: coding, python."
---

# Python REST API Validator

A runnable Python script that calls one endpoint and fails loudly if the status code, required headers, or JSON shape differ from what you expect, ready to drop into CI or a post-deploy smoke test.

## When to use

Use this skill when an endpoint's status code, headers, and JSON body need an automated check that can run in CI or as a smoke test after each deploy. Do not use it for load testing, full contract test suites across many endpoints, or mocking an API.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Write one function that sends the request and returns a list of failure strings, so the script works both imported and from the command line.
3. Check the status code first, then each required header, then parse the body and validate it against the schema when one is given.
4. Read tokens and secrets from environment variables, with a clear error when a required one is missing.
5. Print every failure with expected and actual values and exit non-zero on any failure, so CI marks the run red.
6. Add a usage comment naming the pip packages and the run command, then confirm the script runs against the example inputs.

## Inputs

- **Base URL** (free text, e.g. "https://api.example.com")
- **Endpoint path** (free text, e.g. "/v1/resource")
- **HTTP method** (choose one: GET, POST, PUT, DELETE, PATCH)
- **Expected status code** (number from 100 to 599)
- **Request headers (optional)** (longer free text)
- **Required response headers (optional)** (longer free text)
- **JSON Schema for the body (optional)** (longer free text)
- **Request body (optional)** (longer free text)

## Output

One python code fence with the complete script (imports, validator function, command-line entry point), followed by a single line with the command to run it.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Python REST API Validator Script

Write a Python script that validates one REST endpoint.

- Base URL: {{Base URL}}
- Endpoint path: {{Endpoint path}}
- HTTP method: {{HTTP method}}
- Expected status code: {{Expected status code}}
- Request headers (optional): {{Request headers (optional)}}
- Required response headers (optional): {{Required response headers (optional)}}
- JSON Schema for the body (optional): {{JSON Schema for the body (optional)}}
- Request body (optional): {{Request body (optional)}}

Build the script around a single function that sends the request and returns a list of failures, so it can be imported from a test as well as run from the command line. Use requests for the call and jsonschema for the body check; when no schema is given, only confirm the body parses as JSON. Read secrets such as bearer tokens from environment variables rather than hard-coding them, and fail with a clear message when a required one is missing. Print each failed check on its own line with the expected and actual values, and exit with a non-zero code when any check fails so CI picks it up. Add a short usage comment at the top of the file that lists the pip packages to install.

Return the full script in a single code fence labeled python, followed by one line stating the command to run it.

## Pitfalls

- Stopping at the first failed check, which hides the other failures and makes the user re-run the script several times.
- Hard-coding a bearer token in the file, which ends up committed to version control.
- Treating a 3xx redirect as a failure when the client follows redirects by default, so the expected code never matches.
