api-tools

What this skill does

# 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": "[email protected]"}' \
     https://api.example.com/users

# POST with form data
curl -X POST \
     -F "[email protected]" \
     -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 protected]

# 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 \
  [email protected]

# 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: [email protected]
  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: