Skip to main content
Version: 3.17

Getting Started with Apache APISIX

The Getting Started tutorials are contributed by API7.ai.

Apache APISIX is an open-source, high-performance API gateway and AI gateway built for cloud-native architectures. It is a top-level project of the Apache Software Foundation. It provides dynamic routing, load balancing, authentication, rate limiting, observability, and 100+ plugins for managing API traffic at scale.

This guide walks you through installing APISIX locally, verifying the installation, and configuring your first API route.

Prerequisites#

Before you begin, ensure you have the following installed:

  • Docker (version 20.10 or later) — used to run APISIX and etcd containers
  • curl — used to send requests to APISIX for validation

APISIX uses etcd as its configuration store. The quickstart script handles etcd setup automatically.

Install APISIX#

APISIX can be installed with a single command using the quickstart script:

curl -sL https://run.api7.ai/apisix/quickstart | sh

This script starts two Docker containers:

  • apisix-quickstart — the APISIX gateway, listening on ports 9080 (HTTP) and 9443 (HTTPS)
  • etcd — the configuration store

Both containers use Docker host network mode, so APISIX is accessible directly from localhost.

You will see the following message once APISIX is ready:

✔ APISIX is ready!
caution

The quickstart script disables Admin API authorization by default for ease of use. Always enable Admin API authentication in production environments. See the Admin API documentation for details.

Alternative Installation Methods#

MethodUse CaseDocumentation
Docker ComposeProduction-like local setup with custom configurationapisix-docker
Helm ChartKubernetes deploymentapisix-helm-chart
RPM PackageCentOS/RHEL bare-metal installationInstallation Guide
Source BuildDevelopment and custom buildsHow to Build

Verify the Installation#

Send a request to confirm APISIX is running:

curl "http://127.0.0.1:9080" --head | grep Server

Expected response:

Server: APISIX/3.16.0

The version number reflects the APISIX release you installed.

You can also check the Admin API:

curl "http://127.0.0.1:9180/apisix/admin/routes" | head -c 200

This should return a JSON response confirming the Admin API is accessible.

Configure Your First Route#

A route tells APISIX how to match client requests and forward them to upstream services. Create a route that proxies requests to the public httpbin.org service:

curl -i "http://127.0.0.1:9180/apisix/admin/routes/1" -X PUT -d '
{
  "uri": "/get",
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

Now test the route:

curl "http://127.0.0.1:9080/get"

You should receive a JSON response from httpbin.org, confirming that APISIX is proxying requests correctly.

Add a Plugin#

APISIX provides 100+ built-in plugins for authentication, traffic control, observability, and more. Add rate limiting to the route you just created:

curl -i "http://127.0.0.1:9180/apisix/admin/routes/1" -X PATCH -d '
{
  "plugins": {
    "limit-count": {
      "count": 5,
      "time_window": 60,
      "rejected_code": 429,
      "key_type": "var",
      "key": "remote_addr"
    }
  }
}'

This limits each client IP to 5 requests per minute. Send more than 5 requests within 60 seconds to see the rate limit in action:

for i in $(seq 1 7); do
  echo "Request $i:"
  curl -s -o /dev/null -w "HTTP %{http_code}\n" "http://127.0.0.1:9080/get"
done

Requests 1-5 should return HTTP 200, while requests 6-7 should return HTTP 429.

Access the Dashboard#

APISIX includes a built-in Dashboard UI for visual route and plugin management, accessible at:

http://127.0.0.1:9180/ui

For more details, see the Apache APISIX Dashboard documentation.

Clean Up#

To stop and remove the quickstart containers:

docker rm -f apisix-quickstart etcd

Troubleshooting#

APISIX container fails to start

Check if ports 9080, 9180, or 9443 are already in use:

lsof -i :9080 -i :9180 -i :9443

etcd connection errors

Ensure the etcd container is running:

docker ps | grep etcd

If etcd is not running, restart both containers by re-running the quickstart script.

Admin API returns 401 Unauthorized

If you have enabled Admin API authentication, include the API key in your requests:

curl -H "X-API-KEY: your-admin-key" "http://127.0.0.1:9180/apisix/admin/routes"

Next Steps#

Now that APISIX is running, explore these tutorials to learn core features: