Apache APISIX Cheat Sheet

Overview

Apache APISIX is a dynamic, real-time, high-performance cloud-native API gateway built on top of Nginx and OpenResty. It provides rich traffic management features including load balancing, dynamic upstream, canary releases, service discovery, rate limiting, and over 80 built-in plugins for authentication, observability, and traffic control.

APISIX uses etcd as its configuration store, enabling dynamic configuration changes without restarts. It supports gRPC, WebSocket, MQTT, HTTP/2, and HTTP/3 protocols, making it suitable for microservices, Kubernetes ingress, and API management. APISIX also provides a dashboard for visual management and supports custom plugins in Lua, Java, Python, Go, and WebAssembly.

Installation

Docker Compose

git clone https://github.com/apache/apisix-docker.git
cd apisix-docker/example
docker compose up -d

# Components:
# APISIX: localhost:9080 (proxy), localhost:9180 (Admin API)
# etcd: localhost:2379
# APISIX Dashboard: localhost:9000

Helm Chart (Kubernetes)

helm repo add apisix https://charts.apiseven.com
helm repo update

helm install apisix apisix/apisix \
  --namespace apisix --create-namespace \
  --set gateway.type=NodePort \
  --set admin.allow.ipList="{0.0.0.0/0}"

Standalone Binary

# Install dependencies
sudo apt-get install -y libreadline-dev libpcre3-dev libssl-dev

# Install via RPM/DEB
sudo yum install -y apisix
# or
sudo apt-get install -y apisix

# Start
apisix start

# Stop
apisix stop

Admin API

Route Management

# Create a route
curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \
  -d '{
    "uri": "/api/users/*",
    "methods": ["GET", "POST"],
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "backend1:8080": 1,
        "backend2:8080": 1
      }
    }
  }'

# Get a route
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1"

# List all routes
curl http://127.0.0.1:9180/apisix/admin/routes \
  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1"

# Delete a route
curl -X DELETE http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1"

Upstream Management

# Create an upstream
curl -X PUT http://127.0.0.1:9180/apisix/admin/upstreams/1 \
  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \
  -d '{
    "type": "roundrobin",
    "nodes": {
      "backend1:8080": 3,
      "backend2:8080": 2,
      "backend3:8080": 1
    },
    "retries": 3,
    "timeout": {
      "connect": 6,
      "send": 6,
      "read": 6
    },
    "checks": {
      "active": {
        "http_path": "/health",
        "healthy": { "interval": 5, "successes": 2 },
        "unhealthy": { "interval": 3, "http_failures": 3 }
      }
    }
  }'

# Reference upstream in route
curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \
  -d '{
    "uri": "/api/*",
    "upstream_id": "1"
  }'

Plugins

Authentication

# Key Authentication
curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \
  -d '{
    "uri": "/api/*",
    "plugins": {
      "key-auth": {}
    },
    "upstream_id": "1"
  }'

# Create a consumer with API key
curl -X PUT http://127.0.0.1:9180/apisix/admin/consumers/user1 \
  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \
  -d '{
    "username": "user1",
    "plugins": {
      "key-auth": {
        "key": "my-api-key-123"
      }
    }
  }'

# JWT Authentication
curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/2 \
  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \
  -d '{
    "uri": "/secure/*",
    "plugins": {
      "jwt-auth": {}
    },
    "upstream_id": "1"
  }'

Rate Limiting

curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \
  -d '{
    "uri": "/api/*",
    "plugins": {
      "limit-req": {
        "rate": 100,
        "burst": 50,
        "rejected_code": 429,
        "key_type": "var",
        "key": "remote_addr"
      },
      "limit-count": {
        "count": 1000,
        "time_window": 3600,
        "rejected_code": 429,
        "key": "remote_addr"
      }
    },
    "upstream_id": "1"
  }'

Common Plugins

Plugin	Category	Description
`key-auth`	Auth	API key authentication
`jwt-auth`	Auth	JWT token validation
`basic-auth`	Auth	HTTP basic auth
`openid-connect`	Auth	OIDC/OAuth2
`limit-req`	Traffic	Request rate limiting
`limit-count`	Traffic	Request count limiting
`limit-conn`	Traffic	Connection limiting
`proxy-cache`	Traffic	Response caching
`cors`	Security	CORS headers
`ip-restriction`	Security	IP whitelist/blacklist
`uri-blocker`	Security	URI pattern blocking
`prometheus`	Observability	Metrics export
`zipkin`	Observability	Distributed tracing
`kafka-logger`	Logging	Log to Kafka
`http-logger`	Logging	Log to HTTP endpoint
`grpc-transcode`	Protocol	gRPC to HTTP
`redirect`	Traffic	URL redirects
`response-rewrite`	Transform	Modify responses

Configuration

Config File (`conf/config.yaml`)

apisix:
  node_listen: 9080
  admin_listen:
    ip: 0.0.0.0
    port: 9180
  admin_key:
    - name: admin
      key: edd1c9f034335f136f87ad84b625c8f1
      role: admin
  ssl:
    enable: true
    listen_port: 9443

deployment:
  role: traditional
  role_traditional:
    config_provider: etcd
  etcd:
    host:
      - "http://127.0.0.1:2379"
    prefix: "/apisix"

plugin_attr:
  prometheus:
    export_uri: /apisix/prometheus/metrics
    export_addr:
      ip: 0.0.0.0
      port: 9091

Advanced Usage

Service Discovery

# Consul service discovery
curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \
  -d '{
    "uri": "/api/*",
    "upstream": {
      "service_name": "my-service",
      "discovery_type": "consul",
      "type": "roundrobin"
    }
  }'

Canary Release

curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \
  -d '{
    "uri": "/api/*",
    "plugins": {
      "traffic-split": {
        "rules": [
          {
            "weighted_upstreams": [
              { "upstream_id": "1", "weight": 90 },
              { "upstream_id": "2", "weight": 10 }
            ]
          }
        ]
      }
    }
  }'

Global Plugins

curl -X PUT http://127.0.0.1:9180/apisix/admin/global_rules/1 \
  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \
  -d '{
    "plugins": {
      "prometheus": {},
      "cors": {
        "allow_origins": "*",
        "allow_methods": "GET,POST,PUT,DELETE"
      }
    }
  }'

Monitoring

# Enable Prometheus metrics
# Access: http://localhost:9091/apisix/prometheus/metrics

# Key metrics:
# apisix_http_status — HTTP status codes
# apisix_bandwidth — request/response bandwidth
# apisix_http_latency — request latency histogram
# apisix_upstream_status — upstream health status
# apisix_http_requests_total — total request count

Troubleshooting

Issue	Solution
502 Bad Gateway	Check upstream health; verify backend is reachable from APISIX
404 Not Found	Verify route URI pattern; check route is active
Admin API 401	Use correct `X-API-KEY` header; check admin key in config
Plugin not loading	Verify plugin is listed in config.yaml `plugins` array
etcd connection failed	Check etcd is running; verify etcd host in config
SSL certificate error	Verify cert/key paths; check certificate chain completeness
Rate limiting not applied	Verify plugin config on route; check key configuration
Hot reload not working	etcd must be healthy; check APISIX error logs