api-tools

# API Tools

## Overview

Tools and techniques for API development, testing, documentation, and debugging.

---

## HTTP Clients

### cURL

```bash
# Basic GET
curl https://api.example.com/users

# GET with headers
curl -H "Authorization: Bearer TOKEN" \
     -H "Accept: application/json" \
     https://api.example.com/users

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

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

# PUT request
curl -X PUT \
     -H "Content-Type: application/json" \
     -d '{"name": "Updated Name"}' \
     https://api.example.com/users/123

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

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

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

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

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

# With authentication
curl -u username:password https://api.example.com/protected
curl --oauth2-bearer TOKEN https://api.example.com/protected

# Measure timing
curl -w "@curl-format.txt" -o /dev/null -s https://api.example.com
```

```txt
# curl-format.txt
     time_namelookup:  %{time_namelookup}s\n
        time_connect:  %{time_connect}s\n
     time_appconnect:  %{time_appconnect}s\n
    time_pretransfer:  %{time_pretransfer}s\n
       time_redirect:  %{time_redirect}s\n
  time_starttransfer:  %{time_starttransfer}s\n
                     ----------\n
          time_total:  %{time_total}s\n
```

### HTTPie

```bash
# GET request (more readable output)
http https://api.example.com/users

# With headers
http https://api.example.com/users \
  Authorization:"Bearer TOKEN" \
  Accept:application/json

# POST with JSON (default)
http POST https://api.example.com/users \
  name=John \
  email=john@example.com

# POST with raw JSON
http POST https://api.example.com/users \
  < user.json

# Form data
http -f POST https://api.example.com/login \
  username=john \
  password=secret

# File upload
http -f POST https://api.example.com/upload \
  file@document.pdf

# Download file
http --download https://api.example.com/files/document.pdf

# Session persistence
http --session=user-session POST https://api.example.com/login
http --session=user-session GET https://api.example.com/profile

# Only headers
http --headers https://api.example.com/users

# Only body
http --body https://api.example.com/users
```

---

## API Testing

### Postman Collections

```json
{
  "info": {
    "name": "User API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://api.example.com"
    },
    {
      "key": "token",
      "value": ""
    }
  ],
  "item": [
    {
      "name": "Auth",
      "item": [
        {
          "name": "Login",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/auth/login",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\"email\": \"{{email}}\", \"password\": \"{{password}}\"}"
            }
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "pm.test('Status code is 200', function () {",
                  "    pm.response.to.have.status(200);",
                  "});",
                  "",
                  "pm.test('Response has token', function () {",
                  "    var jsonData = pm.response.json();",
                  "    pm.expect(jsonData.token).to.be.a('string');",
                  "    pm.collectionVariables.set('token', jsonData.token);",
                  "});"
                ]
              }
            }
          ]
        }
      ]
    },
    {
      "name": "Users",
      "item": [
        {
          "name": "List Users",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{baseUrl}}/users?page=1&limit=10",
              "query": [
                { "key": "page", "value": "1" },
                { "key": "limit", "value": "10" }
              ]
            },
            "header": [
              { "key": "Authorization", "value": "Bearer {{token}}" }
            ]
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "pm.test('Status code is 200', function () {",
                  "    pm.response.to.have.status(200);",
                  "});",
                  "",
                  "pm.test('Response is an array', function () {",
                  "    var jsonData = pm.response.json();",
                  "    pm.expect(jsonData.data).to.be.an('array');",
                  "});",
                  "",
                  "pm.test('Response time is less than 500ms', function () {",
                  "    pm.expect(pm.response.responseTime).to.be.below(500);",
                  "});"
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}
```

### Newman CLI

```bash
# Run Postman collection
newman run collection.json

# With environment
newman run collection.json -e environment.json

# Generate HTML report
newman run collection.json \
  --reporters cli,html \
  --reporter-html-export report.html

# Run specific folder
newman run collection.json --folder "Users"

# With iteration data
newman run collection.json -d data.json -n 10

# Set environment variables
newman run collection.json \
  --env-var "baseUrl=https://staging.api.example.com" \
  --env-var "token=xxx"
```

---

## OpenAPI / Swagger

### OpenAPI Specification

```yaml
# openapi.yaml
openapi: 3.0.3
info:
  title: User API
  description: API for managing users
  version: 1.0.0
  contact:
    email: api@example.com
  license:
    name: MIT

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging

tags:
  - name: Users
    description: User management operations
  - name: Auth
    description: Authentication operations

paths:
  /users:
    get:
      summary: List users
      description: Returns a paginated list of users
      operationId: listUsers
      tags:
        - Users
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Items per page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: search
          in: query
          description: Search term
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      summary: Create user
      operationId: createUser
      tags:
        - Users
      security:
        - bearerAuth: []
      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':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /users/{id}:
    get:
      summary: Get user by ID
      operationId: getUserById
      tags:
        - Users
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        email:
          type: string
          format: email
          example: "user@example.com"
        name:
          type: string
          example: "John Doe"
        role:
          type: string
          enum: [user, admin]
          default: user
        createdAt:
          type: string
          format: date-time

    CreateUser:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 8
        name:
          type: string

    UserList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        totalPages:
          type: integer

    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
```

### Generate Client SDK

```bash
# Generate TypeScript client
npx openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./generated/client

# Generate Python client
openapi-generator generate \
  -i openapi.yaml \
  -g python \
  -o ./generated/python-client
```

---

## Mock Servers

### Prism (OpenAPI Mock Server)

```bash
# Start mock server
npx @stoplight/prism-cli mock openapi.yaml

# With dynamic responses
npx @stoplight/prism-cli mock openapi.yaml --dynamic

# Custom port
npx @stoplight/prism-cli mock openapi.yaml -p 4010
```

### JSON Server (Quick REST API)

```json
// db.json
{
  "users": [
    { "id": 1, "name": "John", "email": "john@example.com" },
    { "id": 2, "name": "Jane", "email": "jane@example.com" }
  ],
  "posts": [
    { "id": 1, "title": "Hello World", "userId": 1 }
  ]
}
```

```bash
# Start server
npx json-server --watch db.json --port 3001

# Routes automatically created:
# GET    /users
# GET    /users/1
# POST   /users
# PUT    /users/1
# DELETE /users/1
# GET    /posts?userId=1
```

---

## API Debugging

### Request/Response Logging

```typescript
import axios from 'axios';

// Request interceptor
axios.interceptors.request.use((config) => {
  console.log('Request:', {
    method: config.method?.toUpperCase(),
    url: config.url,
    params: config.params,
    data: config.data,
    headers: config.headers,
  });
  return config;
});

// Response interceptor
axios.interceptors.response.use(
  (response) => {
    console.log('Response:', {
      status: response.status,
      headers: response.headers,
      data: response.data,
    });
    return response;
  },
  (error) => {
    console.log('Error:', {
      status: error.response?.status,
      data: error.response?.data,
    });
    return Promise.reject(error);
  }
);
```

---

## Related Skills

- [[api-design]] - API design patterns
- [[testing-strategies]] - API testing
- [[backend]] - Backend development