API testing tools for technical writers

This guide demonstrates various tools technical writers use to test and document APIs, using our Customer Management API as examples.

1. cURL (Essential - Works everywhere)

Basic operations

# Create customer
curl -X POST 'http://localhost:8080/customer' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Alice Johnson",
    "id": "CUST001",
    "phone": "555-0123",
    "type": "VIP",
    "address": {
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zipCode": "10001",
      "country": "USA"
    }
  }'

# Get customer by ID
curl -X GET 'http://localhost:8080/customer/CUST001' \
  -H 'Accept: application/json'

# Search with filters
curl -X GET 'http://localhost:8080/customers/search?name=Alice&type=VIP&page=0&size=10' \
  -H 'Accept: application/json'

# Partial update (PATCH)
curl -X PATCH 'http://localhost:8080/customer/CUST001' \
  -H 'Content-Type: application/json' \
  -d '{"phone": "555-9999", "type": "PREMIUM"}'

# Batch create customers
curl -X POST 'http://localhost:8080/customers/batch' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "name": "Bob Smith",
      "id": "CUST002",
      "phone": "555-0124",
      "type": "BUSINESS",
      "address": {"street": "456 Oak Ave", "city": "Boston", "state": "MA", "zipCode": "02101", "country": "USA"}
    },
    {
      "name": "Carol Davis",
      "id": "CUST003",
      "phone": "555-0125",
      "type": "INDIVIDUAL",
      "address": {"street": "789 Pine St", "city": "Seattle", "state": "WA", "zipCode": "98101", "country": "USA"}
    }
  ]'

2. Postman (Most popular GUI tool)

Collection structure for documentation:

Customer Management API/
├── Single Customer Operations/
│   ├── Create Customer (POST /customer)
│   ├── Update Customer (PUT /customer)
│   ├── Partial Update (PATCH /customer/{id})
│   ├── Get Customer (GET /customer/{id})
│   └── Delete Customer (DELETE /customer/{id})
└── Multiple Customer Operations/
    ├── Batch Create (POST /customers/batch)
    ├── Get All Customers (GET /customers)
    └── Search Customers (GET /customers/search)

Postman environment variables:

{
  "baseUrl": "http://localhost:8080",
  "customerId": "CUST001",
  "pageSize": "10"
}

Pre-request scripts (for dynamic data):

// Generate unique customer ID
pm.globals.set("customerId", "CUST" + Math.floor(Math.random() * 1000).toString().padStart(3, '0'));

// Set current timestamp
pm.globals.set("timestamp", new Date().toISOString());

3. HTTPie (Developer-friendly CLI)

Install: pip install httpie

# Clean syntax - no quotes needed
http POST localhost:8080/customer \
  name="Alice Johnson" \
  id="CUST001" \
  phone="555-0123" \
  type="VIP" \
  address:='{"street": "123 Main St", "city": "New York", "state": "NY", "zipCode": "10001", "country": "USA"}'

# GET with query parameters
http GET localhost:8080/customers/search name==Alice type==VIP page==0 size==10

# PATCH is intuitive
http PATCH localhost:8080/customer/CUST001 phone="555-9999" type="PREMIUM"

4. Insomnia (Alternative to Postman)

Workspace organization:

Folder: “Customer CRUD”
Folder: “Batch & Search Operations”
Environment: “Development” (localhost:8080)
Environment: “Production” (api.example.com)

Template variables:

/customer/
/customers?page={"layout"=>"default", "title"=>"API testing tools for technical writers", "description"=>"Comprehensive guide to tools for testing and documenting APIs with practical examples", "content"=>"# API testing tools for technical writers\n\nThis guide demonstrates various tools technical writers use to test and document APIs, using our Customer Management API as examples.\n\n## 1. **cURL** (Essential - Works everywhere)\n\n### Basic operations\n```bash\n# Create customer\ncurl -X POST 'http://localhost:8080/customer' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"name\": \"Alice Johnson\",\n    \"id\": \"CUST001\",\n    \"phone\": \"555-0123\",\n    \"type\": \"VIP\",\n    \"address\": {\n      \"street\": \"123 Main St\",\n      \"city\": \"New York\",\n      \"state\": \"NY\",\n      \"zipCode\": \"10001\",\n      \"country\": \"USA\"\n    }\n  }'\n\n# Get customer by ID\ncurl -X GET 'http://localhost:8080/customer/CUST001' \\\n  -H 'Accept: application/json'\n\n# Search with filters\ncurl -X GET 'http://localhost:8080/customers/search?name=Alice&type=VIP&page=0&size=10' \\\n  -H 'Accept: application/json'\n\n# Partial update (PATCH)\ncurl -X PATCH 'http://localhost:8080/customer/CUST001' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"phone\": \"555-9999\", \"type\": \"PREMIUM\"}'\n\n# Batch create customers\ncurl -X POST 'http://localhost:8080/customers/batch' \\\n  -H 'Content-Type: application/json' \\\n  -d '[\n    {\n      \"name\": \"Bob Smith\",\n      \"id\": \"CUST002\",\n      \"phone\": \"555-0124\",\n      \"type\": \"BUSINESS\",\n      \"address\": {\"street\": \"456 Oak Ave\", \"city\": \"Boston\", \"state\": \"MA\", \"zipCode\": \"02101\", \"country\": \"USA\"}\n    },\n    {\n      \"name\": \"Carol Davis\",\n      \"id\": \"CUST003\",\n      \"phone\": \"555-0125\",\n      \"type\": \"INDIVIDUAL\",\n      \"address\": {\"street\": \"789 Pine St\", \"city\": \"Seattle\", \"state\": \"WA\", \"zipCode\": \"98101\", \"country\": \"USA\"}\n    }\n  ]'\n```\n\n## 2. **Postman** (Most popular GUI tool)\n\n### Collection structure for documentation:\n```\nCustomer Management API/\n├── Single Customer Operations/\n│   ├── Create Customer (POST /customer)\n│   ├── Update Customer (PUT /customer)\n│   ├── Partial Update (PATCH /customer/{id})\n│   ├── Get Customer (GET /customer/{id})\n│   └── Delete Customer (DELETE /customer/{id})\n└── Multiple Customer Operations/\n    ├── Batch Create (POST /customers/batch)\n    ├── Get All Customers (GET /customers)\n    └── Search Customers (GET /customers/search)\n```\n\n### Postman environment variables:\n```json\n{\n  \"baseUrl\": \"http://localhost:8080\",\n  \"customerId\": \"CUST001\",\n  \"pageSize\": \"10\"\n}\n```\n\n### Pre-request scripts (for dynamic data):\n```javascript\n// Generate unique customer ID\npm.globals.set(\"customerId\", \"CUST\" + Math.floor(Math.random() * 1000).toString().padStart(3, '0'));\n\n// Set current timestamp\npm.globals.set(\"timestamp\", new Date().toISOString());\n```\n\n## 3. **HTTPie** (Developer-friendly CLI)\n\nInstall: `pip install httpie`\n\n```bash\n# Clean syntax - no quotes needed\nhttp POST localhost:8080/customer \\\n  name=\"Alice Johnson\" \\\n  id=\"CUST001\" \\\n  phone=\"555-0123\" \\\n  type=\"VIP\" \\\n  address:='{\"street\": \"123 Main St\", \"city\": \"New York\", \"state\": \"NY\", \"zipCode\": \"10001\", \"country\": \"USA\"}'\n\n# GET with query parameters\nhttp GET localhost:8080/customers/search name==Alice type==VIP page==0 size==10\n\n# PATCH is intuitive\nhttp PATCH localhost:8080/customer/CUST001 phone=\"555-9999\" type=\"PREMIUM\"\n```\n\n## 4. **Insomnia** (Alternative to Postman)\n\n### Workspace organization:\n- Folder: \"Customer CRUD\"\n- Folder: \"Batch & Search Operations\"\n- Environment: \"Development\" (localhost:8080)\n- Environment: \"Production\" (api.example.com)\n\n### Template variables:\n```\n{{ baseUrl }}/customer/{{ customerId }}\n{{ baseUrl }}/customers?page={{ page }}&size={{ size }}\n```\n\n## 5. **VS Code REST Client extension**\n\nCreate `.http` files for documentation:\n\n```http\n### Variables\n@baseUrl = http://localhost:8080\n@customerId = CUST001\n\n### Create Customer\nPOST {{baseUrl}}/customer\nContent-Type: application/json\n\n{\n  \"name\": \"Alice Johnson\",\n  \"id\": \"{{customerId}}\",\n  \"phone\": \"555-0123\",\n  \"type\": \"VIP\",\n  \"address\": {\n    \"street\": \"123 Main St\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"zipCode\": \"10001\",\n    \"country\": \"USA\"\n  }\n}\n\n### Get Customer\nGET {{baseUrl}}/customer/{{customerId}}\nAccept: application/json\n\n### Search Customers\nGET {{baseUrl}}/customers/search?name=Alice&type=VIP&page=0&size=10\nAccept: application/json\n\n### Update Customer Phone\nPATCH {{baseUrl}}/customer/{{customerId}}\nContent-Type: application/json\n\n{\n  \"phone\": \"555-9999\"\n}\n```\n\n## 6. **Browser testing** (for GET requests)\n\nDirect browser URLs for quick testing:\n```\nhttp://localhost:8080/customers\nhttp://localhost:8080/customers?page=0&size=5\nhttp://localhost:8080/customers/search?type=VIP\nhttp://localhost:8080/customers/search?name=Alice&city=New%20York\nhttp://localhost:8080/customer/CUST001\n```\n\n## 7. **OpenAPI/Swagger tools**\n\n### Swagger UI (Built-in)\n```\nhttp://localhost:8080/swagger-ui/index.html\n```\n\n### Swagger Editor (Online)\n- Import: `http://localhost:8080/v3/api-docs.yaml`\n- Test directly in editor\n\n### ReDoc (Alternative documentation)\n- Cleaner docs format\n- Can be integrated into documentation sites\n\n## 8. **Bruno** (Open source Postman alternative)\n\nLightweight, fast alternative with collections stored as files:\n```\ncollections/\n├── customer-management.json\n├── environments/\n│   ├── development.json\n│   └── production.json\n```\n\n## 9. **Paw** (Mac-only, Premium)\n\nAdvanced features for technical writers:\n- Dynamic values and variables\n- Code generation in multiple languages\n- Beautiful documentation export\n\n## 10. **Testing in documentation**\n\n### Example response documentation:\n```json\n// GET /customer/CUST001 Response (200 OK)\n{\n  \"name\": \"Alice Johnson\",\n  \"id\": \"CUST001\",\n  \"phone\": \"555-0123\",\n  \"type\": \"VIP\",\n  \"address\": {\n    \"street\": \"123 Main St\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"zipCode\": \"10001\",\n    \"country\": \"USA\",\n    \"formattedAddress\": \"123 Main St, New York, NY 10001\"\n  },\n  \"businessCustomer\": false,\n  \"highValueCustomer\": true,\n  \"city\": \"New York\"\n}\n```\n\n### Error response examples:\n```json\n// GET /customer/INVALID (404 Not Found)\n{\n  \"error\": \"Customer not found\",\n  \"customerID\": \"INVALID\",\n  \"timestamp\": \"2024-01-21T10:30:00Z\"\n}\n```\n\n## **Recommendations for technical writers:**\n\n1. **Master cURL first** - Works everywhere, easy to document\n2. **Use Postman/Insomnia for complex workflows** - GUI makes testing faster\n3. **HTTPie for cleaner CLI examples** - More readable than cURL in docs\n4. **VS Code REST Client for living documentation** - Keep tests with code\n5. **Browser for quick GET testing** - Fastest for simple checks\n6. **Swagger UI for interactive docs** - Great for user-facing documentation\n\n## **Testing checklist for documentation:**\n\n- [ ] Test all HTTP methods (GET, POST, PUT, PATCH, DELETE)\n- [ ] Verify all query parameters work as documented\n- [ ] Test error conditions (404, 400, 500)\n- [ ] Validate request/response examples\n- [ ] Check pagination and filtering\n- [ ] Test with various data types and edge cases\n- [ ] Verify authentication (if applicable)\n- [ ] Test rate limiting (if applicable)\n\nEach tool has its strengths - technical writers often use multiple tools depending on the task: cURL for documentation examples, Postman for complex testing workflows, and browser testing for quick verification.", "dir"=>"/tech-writer-reference/reference/", "name"=>"tools-comparison.md", "path"=>"tech-writer-reference/reference/tools-comparison.md", "url"=>"/tech-writer-reference/reference/tools-comparison.html"}&size=

5. VS Code REST Client extension

Create .http files for documentation:

### Variables
@baseUrl = http://localhost:8080
@customerId = CUST001

### Create Customer
POST /customer
Content-Type: application/json

{
  "name": "Alice Johnson",
  "id": "",
  "phone": "555-0123",
  "type": "VIP",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "USA"
  }
}

### Get Customer
GET /customer/
Accept: application/json

### Search Customers
GET /customers/search?name=Alice&type=VIP&page=0&size=10
Accept: application/json

### Update Customer Phone
PATCH /customer/
Content-Type: application/json

{
  "phone": "555-9999"
}

6. Browser testing (for GET requests)

Direct browser URLs for quick testing:

http://localhost:8080/customers
http://localhost:8080/customers?page=0&size=5
http://localhost:8080/customers/search?type=VIP
http://localhost:8080/customers/search?name=Alice&city=New%20York
http://localhost:8080/customer/CUST001

7. OpenAPI/Swagger tools

Swagger UI (Built-in)

http://localhost:8080/swagger-ui/index.html

Swagger Editor (Online)

Import: http://localhost:8080/v3/api-docs.yaml
Test directly in editor

ReDoc (Alternative documentation)

Cleaner docs format
Can be integrated into documentation sites

8. Bruno (Open source Postman alternative)

Lightweight, fast alternative with collections stored as files:

collections/
├── customer-management.json
├── environments/
│   ├── development.json
│   └── production.json

9. Paw (Mac-only, Premium)

Advanced features for technical writers:

Dynamic values and variables
Code generation in multiple languages
Beautiful documentation export

10. Testing in documentation

Example response documentation:

// GET /customer/CUST001 Response (200 OK)
{
  "name": "Alice Johnson",
  "id": "CUST001",
  "phone": "555-0123",
  "type": "VIP",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "USA",
    "formattedAddress": "123 Main St, New York, NY 10001"
  },
  "businessCustomer": false,
  "highValueCustomer": true,
  "city": "New York"
}

Error response examples:

// GET /customer/INVALID (404 Not Found)
{
  "error": "Customer not found",
  "customerID": "INVALID",
  "timestamp": "2024-01-21T10:30:00Z"
}

Recommendations for technical writers:

Master cURL first - Works everywhere, easy to document
Use Postman/Insomnia for complex workflows - GUI makes testing faster
HTTPie for cleaner CLI examples - More readable than cURL in docs
VS Code REST Client for living documentation - Keep tests with code
Browser for quick GET testing - Fastest for simple checks
Swagger UI for interactive docs - Great for user-facing documentation

Testing checklist for documentation:

Test all HTTP methods (GET, POST, PUT, PATCH, DELETE)
Verify all query parameters work as documented
Test error conditions (404, 400, 500)
Validate request/response examples
Check pagination and filtering
Test with various data types and edge cases
Verify authentication (if applicable)
Test rate limiting (if applicable)

Each tool has its strengths - technical writers often use multiple tools depending on the task: cURL for documentation examples, Postman for complex testing workflows, and browser testing for quick verification.