API Contract Tester

Validates HTTP/REST endpoints against contract specifications. Tests status codes, headers (Content-Type), and JSON response schema conformity using curl or test clients.

1. Purpose

Verify that API routes fulfill their external contracts before deployment.

2. When to Use

Use this skill when:

• Verifying newly implemented HTTP routes.
• Testing error responses (400, 401, 404, 429).
• Auditing response schema against OpenAPI / JSON Schema contracts.

3. When Not to Use

• Do not use for unit testing internal functions; use test-runner-debugger.

4. Required Inputs

• endpoint: URL path (e.g. http://localhost:3000/api/users).
• method: GET, POST, PUT, DELETE.
• expected_status: Expected HTTP status code (e.g. 200, 400).

5. Missing-Input Behavior

1. If endpoint is missing: ask for target URL.
2. Default method to GET if unspecified.

6. Procedure

Follow these numbered actions:

1. Action 1: Formulate Test Request
   • Construct curl -s -i -X <METHOD> <URL>.
2. Action 2: Execute Request
   • Capture HTTP status code, headers, and body.
3. Action 3: Validate Status & Headers
   • Check if status matches expected_status.
   • Check Content-Type: application/json.
4. Action 4: Validate Body Schema
   • Verify required keys exist and match types.
5. Action 5: Emit Contract Report
   • Format per Section 8.

7. Decision Rules

• If status code matches but payload is missing required schema keys: mark as CONTRACT_VIOLATION.

8. Output Format

Emit the report using this template:

### API Contract Test Report: [METHOD] [Endpoint]

- **Status**: [PASSED | FAILED | CONTRACT_VIOLATION]
- **HTTP Code**: [Observed] (Expected: [Expected])
- **Content-Type**: `[Header]`

#### Payload Validation
- [x] Status code matches contract
- [x] Response body valid JSON
- [x] Required keys present: `[keys]`

9. Verification Checklist

• HTTP status code matches expected.
• Content-Type header verified.
• Response body matches schema.

10. Common Failures and Recovery

11. Stop or Escalation Conditions

Stop and ask the user when:

• Endpoint triggers destructive live external actions (e.g. real credit card charges).

12. Examples

Example 1: Successful Execution

Input:

Endpoint: http://localhost:3000/health
Method: GET
Expected: 200

Output:

### API Contract Test Report: GET /health

- **Status**: PASSED
- **HTTP Code**: 200 (Expected: 200)
- **Content-Type**: `application/json; charset=utf-8`

#### Payload Validation
- [x] Status code matches contract
- [x] Response body valid JSON (`{"status":"ok"}`)
- [x] Required keys present: `status`

Example 2: Ambiguous or Missing Input

Input:

Test API.

Output:

### API Contract Test Report: Halted - Missing Endpoint

- **Status**: Halted

Please provide the API endpoint URL and expected HTTP status code.

Example 3: Expected Final Output

Output:

### API Contract Test Report: POST /api/login

- **Status**: PASSED
- **HTTP Code**: 401 (Expected: 401)
- **Content-Type**: `application/json`