API Testing & Debugging Guide: From cURL to Online Tools

Dev Tools

HTTP Request Methods

Method Purpose Idempotent Safe
GET Retrieve a resource ✅ ✅
POST Create a resource ❌ ❌
PUT Full update ✅ ❌
PATCH Partial update ❌ ❌
DELETE Delete a resource ✅ ❌
HEAD Retrieve headers only ✅ ✅
OPTIONS CORS preflight ✅ ✅

Common Request Headers

Header Description Example
Content-Type Request body format application/json
Accept Expected response format application/json
Authorization Authentication credentials Bearer token...
User-Agent Client identifier Mozilla/5.0...
Cookie Cookie session=abc123
X-Request-ID Request tracing ID UUID

Common Content-Type Values

Value Purpose
application/json JSON data
application/x-www-form-urlencoded Form data
multipart/form-data File upload
text/plain Plain text
text/html HTML

Authentication Methods

1. Bearer Token (Most Common)

# cURL
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  https://api.example.com/users

# JavaScript
fetch('https://api.example.com/users', {
  headers: {
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiJ9...',
  },
});

2. Basic Auth

# cURL (encodes automatically)
curl -u username:password https://api.example.com/users

# Manual encoding
# Base64("username:password") = "dXNlcm5hbWU6cGFzc3dvcmQ="
curl -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
  https://api.example.com/users

3. API Key

# Option 1: Header
curl -H "X-API-Key: your-api-key" \
  https://api.example.com/users

# Option 2: Query parameter
curl "https://api.example.com/users?api_key=your-api-key"

cURL Command Reference

Basic GET Requests

# Simplest GET
curl https://api.example.com/users

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

# Show only response headers
curl -I https://api.example.com/users

# Follow redirects
curl -L https://example.com/redirect

POST Requests

# JSON data
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

# Form data
curl -X POST https://api.example.com/users \
  -d "name=Alice&email=alice@example.com"

# File upload
curl -X POST https://api.example.com/upload \
  -F "file=@photo.jpg" \
  -F "description=My photo"

Advanced Options

# Timeout settings
curl --connect-timeout 5 --max-time 30 https://api.example.com

# Write output to a file
curl -o response.json https://api.example.com/users

# Silent mode (no progress meter)
curl -s https://api.example.com/users

# Verbose output (for debugging)
curl -v https://api.example.com/users

# Skip SSL certificate verification (development only)
curl -k https://self-signed.example.com

# Proxy
curl -x http://proxy:8080 https://api.example.com

# Cookie
curl -b "session=abc123" https://api.example.com/users

# Save and send cookies
curl -c cookies.txt -b cookies.txt https://api.example.com/users

Common HTTP Status Codes

Status Meaning Common Cause
200 OK Success
201 Created POST created successfully
204 No Content DELETE succeeded
301 Moved Permanently Permanent redirect
304 Not Modified Cache hit
400 Bad Request Invalid parameters
401 Unauthorized Not authenticated
403 Forbidden Insufficient permissions
404 Not Found Resource does not exist
409 Conflict Resource conflict
422 Unprocessable Entity Validation failed
429 Too Many Requests Rate limited
500 Internal Server Error Server-side error
502 Bad Gateway Upstream service unavailable
503 Service Unavailable Service overloaded

Testing APIs with ToolsKu

Convert cURL to Code

  1. Open the cURL to Code tool
  2. Paste your cURL command
  3. Select the target language (JavaScript/Python/Go/Java, etc.)
  4. Copy the generated code

Example

# Input cURL
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token123" \
  -d '{"name": "Alice"}'

Converted to JavaScript:

const response = await fetch('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer token123',
  },
  body: JSON.stringify({ name: 'Alice' }),
});
const data = await response.json();

API Debugging Techniques

1. Inspect the Full Request/Response

# -v shows detailed information
curl -v https://api.example.com/users

# Output:
> GET /users HTTP/1.1          ← Request line
> Host: api.example.com        ← Request headers
> Authorization: Bearer ...
>
< HTTP/1.1 200 OK              ← Status line
< Content-Type: application/json ← Response headers
< X-RateLimit-Remaining: 99
<
[{"id": 1, "name": "Alice"}]   ← Response body

2. Pretty-Print JSON Responses

# Format with jq
curl -s https://api.example.com/users | jq

# With python
curl -s https://api.example.com/users | python -m json.tool

# Or use ToolsKu's JSON formatter

3. Measure Response Time

# Detailed timing breakdown
curl -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" \
  -o /dev/null -s https://api.example.com/users

# Output:
# DNS: 0.012s
# Connect: 0.035s
# TTFB: 0.120s
# Total: 0.125s

4. Troubleshoot CORS Issues

Browser error:
Access to fetch at 'https://api.example.com' from origin 'https://app.example.com'
has been blocked by CORS policy

Troubleshooting steps:
1. Inspect the OPTIONS preflight request
   curl -X OPTIONS -H "Origin: https://app.example.com" \
     -H "Access-Control-Request-Method: POST" \
     -i https://api.example.com/users

2. Check the response headers
   Access-Control-Allow-Origin: https://app.example.com
   Access-Control-Allow-Methods: GET, POST, PUT, DELETE
   Access-Control-Allow-Headers: Content-Type, Authorization
   Access-Control-Max-Age: 86400

5. Troubleshoot Authentication Issues

Troubleshooting 401 Unauthorized:
1. Has the token expired? → Check exp with a JWT decoder
2. Is the token format correct? → Check the Bearer prefix
3. Was the token actually sent? → Inspect request headers with curl -v

Troubleshooting 403 Forbidden:
1. Does the user have permission? → Check the user role
2. Is the IP whitelisted? → Check server logs
3. Rate limit exceeded? → Check for 429 status codes

API Testing Best Practices

1. Manage Environment Variables

# Store sensitive information in environment variables
export API_BASE="https://api.example.com"
export API_TOKEN="your-token"

curl -H "Authorization: Bearer $API_TOKEN" "$API_BASE/users"

2. Request Collections

#!/bin/bash
# api-test.sh

BASE="https://api.example.com"
TOKEN="Bearer $API_TOKEN"
HEADER="-H 'Content-Type: application/json' -H 'Authorization: $TOKEN'"

# List users
get_users() { curl -s $HEADER "$BASE/users" | jq; }

# Create a user
create_user() { curl -s -X POST $HEADER -d "$1" "$BASE/users" | jq; }

# Get a single user
get_user() { curl -s $HEADER "$BASE/users/$1" | jq; }

# Usage
get_users
create_user '{"name":"Bob"}'
get_user 1

3. Automated Tests

// Write API tests with fetch
async function testApi() {
  // Test GET
  const listRes = await fetch('/api/users');
  console.assert(listRes.status === 200, 'GET /users should return 200');

  // Test POST
  const createRes = await fetch('/api/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: 'Test' }),
  });
  console.assert(createRes.status === 201, 'POST /users should return 201');

  const created = await createRes.json();
  console.assert(created.name === 'Test', 'Name should match');
}

FAQ

cURL Quoting Issues on Windows?

Windows CMD requires double quotes, and PowerShell has escaping quirks:

# In PowerShell, curl is an alias for Invoke-WebRequest
# Use curl.exe to invoke the real cURL
curl.exe -X POST https://api.example.com/users `
  -H "Content-Type: application/json" `
  -d '{\"name\": \"Alice\"}'

How to Troubleshoot Request Timeouts?

1. Slow DNS resolution? → Check time_namelookup with curl -w
2. Slow connection setup? → Check time_connect with curl -w
3. Slow server processing? → Check time_starttransfer - time_connect with curl -w
4. Slow response transfer? → Check time_total - time_starttransfer with curl -w

Summary

API debugging is part of a developer's daily routine — mastering cURL commands, HTTP Status Codes, authentication methods, and debugging techniques lets you pinpoint API issues fast. ToolsKu's cURL to Code tool and JSON Formatter are great companions for API debugging, helping you test endpoints and inspect responses quickly.

#API testing#HTTP requests#cURL#API debugging#tutorial