API Development

Scaffold, test, document, and debug REST and GraphQL APIs. Use when the user needs to create API endpoints, write integration tests, generate OpenAPI specs, test with curl, mock APIs, or troubleshoot HTTP issues.

Security Scan

The skill is largely coherent with its stated purpose (API development) but contains small inconsistencies and omissions (examples reference shell tools and environment variables that are not declared) that merit caution before use.

Purpose & Capability

Name and description (scaffolding, testing, mocking, OpenAPI generation, debugging) match the SKILL.md contents: curl examples, test runners, and guidance for API workflows are present and expected.

Instruction Scope

The instructions are focused on API tasks (curl, test scripts, OpenAPI generation). However, examples and scripts reference use of Authorization headers (Bearer $TOKEN), file uploads (file=@document.pdf), and piping through jq — which mean the agent or user will supply credentials and local files when following examples. The SKILL.md does not instruct the agent to read arbitrary system files or secrets, but the examples do assume access to user files and environment variables.

Install Mechanism

This is an instruction-only skill with no install spec or code files, so nothing is written to disk by the skill itself (lowest install risk).

Credentials

The skill declares no required environment variables, but examples use $TOKEN and the test scripts expect a reachable BASE URL and local files. Also many examples and the assert_json helper pipe output through jq, yet jq is not declared in the 'required binaries' metadata. The lack of declared env/binary requirements for jq and example tokens is an inconsistency to be aware of.

Persistence & Privilege

Defaults are used (always:false, model invocation allowed). The skill does not request persistent installation or elevated platform privileges.

What to consider before installing

This skill appears to be what it says — a collection of API development recipes — but check a few things before using it: 1) Examples show Authorization: Bearer $TOKEN and file uploads; don't paste real credentials or point tests at production endpoints. 2) The SKILL.md uses jq in many examples but jq is not listed as a required binary — install jq or remove those pipes before running. 3) Review test scripts to ensure they target a safe endpoint (localhost or a test environment) and that any file uploads (file=@...) are intended. 4) Because this is instruction-only, no code is installed, but following commands will make network requests — make sure you trust the target URL. If you want higher assurance, request an explicit list of required tools (jq, jq version), any Node-based scaffolding commands, and confirmation of whether any instructions will read local files beyond what you supply.

Build, test, document, and debug HTTP APIs from the command line. Covers the full API lifecycle: scaffolding endpoints, testing with curl, generating OpenAPI docs, mocking services, and debugging.

When to Use

• Scaffolding new REST or GraphQL endpoints
• Testing APIs with curl or scripts
• Generating or validating OpenAPI/Swagger specs
• Mocking external APIs for development
• Debugging HTTP request/response issues
• Load testing endpoints

Testing APIs with curl

GET requests

# Basic GET
curl -s https://api.example.com/users | jq .

# With headers
curl -s -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://api.example.com/users | jq .

# With query params
curl -s "https://api.example.com/users?page=2&limit=10" | jq .

# Show response headers too
curl -si https://api.example.com/users

POST/PUT/PATCH/DELETE

# POST JSON
curl -s -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "Alice", "email": "[e-mail]"}' | jq .

# PUT (full replace)
curl -s -X PUT https://api.example.com/users/123 \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice Updated", "email": "[e-mail]"}' | jq .

# PATCH (partial update)
curl -s -X PATCH https://api.example.com/users/123 \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice V2"}' | jq .

# DELETE
curl -s -X DELETE https://api.example.com/users/123

# POST form data
curl -s -X POST https://api.example.com/upload \
  -F "file=@document.pdf" \
  -F "description=My document"

Debug requests

# Verbose output (see full request/response)
curl -v https://api.example.com/health 2>&1

# Show only response headers
curl -sI https://api.example.com/health

# Show timing breakdown
curl -s -o /dev/null -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nFirst byte: %{time_starttransfer}s\nTotal: %{time_total}s\n" https://api.example.com/health

# Follow redirects
curl -sL https://api.example.com/old-endpoint

# Save response to file
curl -s -o response.json https://api.example.com/data

API Test Scripts

Bash test runner

#!/bin/bash
# api-test.sh - Simple API test runner
BASE_URL="${1:-http://localhost:3000}"
PASS=0
FAIL=0

assert_status() {
  local method="$1" url="$2" expected="$3" body="$4"
  local args=(-s -o /dev/null -w "%{http_code}" -X "$method")
  if [ -n "$body" ]; then
    args+=(-H "Content-Type: application/json" -d "$body")
  fi
  local status
  status=$(curl "${args[@]}" "$BASE_URL$url")
  if [ "$status" = "$expected" ]; then
    echo "PASS: $method $url -> $status"
    ((PASS++))
  else
    echo "FAIL: $method $url -> $status (expected $expected)"
    ((FAIL++))
  fi
}

assert_json() {
  local url="$1" jq_expr="$2" expected="$3"
  local actual
  actual=$(curl -s "$BASE_URL$url" | jq -r "$jq_expr")
  if [ "$actual" = "$expected" ]; then
    echo "PASS: GET $url | jq '$jq_expr' = $expected"
    ((PASS++))
  else
    echo "FAIL: GET $url | jq '$jq_expr' = $actual (expected $expected)"
    ((FAIL++))
  fi
}

# Health check
assert_status GET /health 200

# CRUD tests
assert_status POST /api/users 201 '{"name":"Test","email":"[e-mail]"}'
assert_status GET /api/users 200
assert_json /api/users '.[-1].name' 'Test'
assert_status DELETE /api/users/1 204

# Auth tests
assert_status GET /api/admin 401
assert_status GET /api/admin 403  # with wrong role

echo ""
echo "Results: $PASS passed, $FAIL failed"
[ "$FAIL" -eq 0 ] && exit 0 || exit 1

Python test runner

#!/usr/bin/env python3
"""api_test.py - API integration test suite."""
import json, sys, urllib.request, urllib.error

BASE = sys.argv[1] if len(sys.argv) > 1 else "http://localhost:3000"
PASS = FAIL = 0

def request(method, path, body=None, headers=None):
    """Make an HTTP request, return (status, body_dict, headers)."""
    url = f"{BASE}{path}"
    data = json.dumps(body).encode() if body else None
    hdrs = {"Content-Type": "application/json", "Accept": "application/json"}
    if headers:
        hdrs.update(headers)
    req = urllib.request.Request(url, data=data, headers=hdrs, method=method)
    try:
        resp = urllib.request.urlopen(req)
        body = json.loads(resp.read().decode()) if resp.read() else None
    except urllib.error.HTTPError as e:
        return e.code, None, dict(e.headers)
    return resp.status, body, dict(resp.headers)

def test(name, fn):
    """Run a test function, track pass/fail."""
    global PASS, FAIL
    try:
        fn()
        print(f"  PASS: {name}")
        PASS += 1
    except AssertionError as e:
        print(f"  FAIL: {name} - {e}")
        FAIL += 1

def assert_eq(actual, expected, msg=""):
    assert actual == expected, f"got {actual}, expected {expected}. {msg}"

# --- Tests ---
print(f"Testing {BASE}\n")

test("GET /health returns 200", lambda: (
    assert_eq(request("GET", "/health")[0], 200)
))

test("POST /api/users creates user", lambda: (
    assert_eq(request("POST", "/api/users", {"name": "Test", "email": "[e-mail]"})[0], 201)
))

test("GET /api/users returns array", lambda: (
    assert_eq(type(request("GET", "/api/users")[1]), list)
))

test("GET /api/notfound returns 404", lambda: (
    assert_eq(request("GET", "/api/notfound")[0], 404)
))

print(f"\nResults: {PASS} passed, {FAIL} failed")
sys.exit(0 if FAIL == 0 else 1)

OpenAPI Spec Generation

Generate from existing endpoints

# Scaffold an OpenAPI 3.0 spec from curl responses
# Run this, then fill in the details
cat > openapi.yaml << 'EOF'
openapi: "3.0.3"
info:
  title: My API
  version: "1.0.0"
  description: API description here
servers:
  - url: http://localhost:3000
    description: Local development
paths:
  /health:
    get:
      summary: Health check
      responses:
        "200":
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
  /api/users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUser"
      responses:
        "201":
          description: User created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: Validation error
  /api/users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: Not found
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        createdAt:
          type: string
          format: date-time
    CreateUser:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
        email:
          type: string
          format: email
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
EOF

Validate OpenAPI spec

# Using npx (no install needed)
npx @redocly/cli lint openapi.yaml

# Quick check: is the YAML valid?
python3 -c "import yaml; yaml.safe_load(open('openapi.yaml'))" && echo "Valid YAML"

Mock Server

Quick mock with Python

#!/usr/bin/env python3
"""mock_server.py - Lightweight API mock from OpenAPI-like config."""
import json, http.server, re, sys

PORT = int(sys.argv[1]) if len(sys.argv) > 1 else 8080

# Define mock routes: (method, path_pattern) -> response
ROUTES = {
    ("GET", "/health"): {"status": 200, "body": {"status": "ok"}},
    ("GET", "/api/users"): {"status": 200, "body": [
        {"id": "1", "name": "Alice", "email": "[e-mail]"},
        {"id": "2", "name": "Bob", "email": "[e-mail]"},
    ]},
    ("POST", "/api/users"): {"status": 201, "body": {"id": "3", "name": "Created"}},
    ("GET", r"/api/users/\w+"): {"status": 200, "body": {"id": "1", "name": "Alice"}},
    ("DELETE", r"/api/users/\w+"): {"status": 204, "body": None},
}

class MockHandler(http.server.BaseHTTPRequestHandler):
    def _handle(self):
        for (method, pattern), response in ROUTES.items():
            if self.command == method and re.fullmatch(pattern, self.path.split('?')[0]):
                self.send_response(response["status"])
                if response["body"] is not None:
                    self.send_header("Content-Type", "application/json")
                    self.end_headers()
                    self.wfile.write(json.dumps(response["body"]).encode())
                else:
                    self.end_headers()
                return
        self.send_response(404)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(json.dumps({"error": "Not found"}).encode())

    do_GET = do_POST = do_PUT = do_PATCH = do_DELETE = _handle

    def log_message(self, fmt, *args):
        print(f"{self.command} {self.path} -> {args[1] if len(args) > 1 else '?'}")

print(f"Mock server on http://localhost:{PORT}")
http.server.HTTPServer(("", PORT), MockHandler).serve_forever()

Run: python3 mock_server.py 8080

Node.js Express Scaffolding

Minimal REST API

// server.js - Minimal Express REST API
const express = require('express');
const app = express();
app.use(express.json());

// In-memory store
const items = new Map();
let nextId = 1;

// CRUD endpoints
app.get('/api/items', (req, res) => {
  const { page = 1, limit = 20 } = req.query;
  const all = [...items.values()];
  const start = (page - 1) * limit;
  res.json({ items: all.slice(start, start + +limit), total: all.length });
});

app.get('/api/items/:id', (req, res) => {
  const item = items.get(req.params.id);
  if (!item) return res.status(404).json({ error: 'Not found' });
  res.json(item);
});

app.post('/api/items', (req, res) => {
  const { name, description } = req.body;
  if (!name) return res.status(400).json({ error: 'name required' });
  const id = String(nextId++);
  const item = { id, name, description: description || '', createdAt: new Date().toISOString() };
  items.set(id, item);
  res.status(201).json(item);
});

app.put('/api/items/:id', (req, res) => {
  if (!items.has(req.params.id)) return res.status(404).json({ error: 'Not found' });
  const item = { ...req.body, id: req.params.id, updatedAt: new Date().toISOString() };
  items.set(req.params.id, item);
  res.json(item);
});

app.delete('/api/items/:id', (req, res) => {
  if (!items.has(req.params.id)) return res.status(404).json({ error: 'Not found' });
  items.delete(req.params.id);
  res.status(204).end();
});

// Error handler
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({ error: 'Internal server error' });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`API running on http://localhost:${PORT}`));

Setup

mkdir my-api && cd my-api
npm init -y
npm install express
node server.js

Debugging Patterns

Check if port is in use

# Linux/macOS
lsof -i :3000
# or
ss -tlnp | grep 3000

# Kill process on port
kill $(lsof -t -i :3000)

Test CORS

# Preflight request
curl -s -X OPTIONS https://api.example.com/users \
  -H "Origin: http://localhost:3000" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Content-Type" \
  -I

Watch for response time regressions

# Quick benchmark (10 requests)
for i in $(seq 1 10); do
  curl -s -o /dev/null -w "%{time_total}\n" http://localhost:3000/api/users
done | awk '{sum+=$1; if($1>max)max=$1} END {printf "Avg: %.3fs, Max: %.3fs\n", sum/NR, max}'

Inspect JWT tokens

# Decode JWT payload (no verification)
echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq .

Tips

• Use jq for JSON response processing: curl -s url | jq '.items[] | {id, name}'
• Set Content-Type header on every request with a body - missing it causes silent 400s
• Use -w '\n' with curl to ensure output ends with a newline
• For large response bodies, pipe to jq -C . | less -R for colored paging
• Test error paths: invalid JSON, missing fields, wrong types, unauthorized, not found
• For WebSocket testing: npx wscat -c ws://localhost:3000/ws