Skip to main content
Version: 2.12

Getting Started

Summary#

This article is a quick start guide for Apache APISIX. The Quick Start is divided into the following three steps:

  1. Install Apache APISIX via Docker Compose.
  2. Create a route and bind it with a Upstream.
  3. Use curl command to verify that the results returned after binding are as expected.

In addition, this article provides some advanced operations on how to use Apache APISIX, including adding authentication, prefixing Route, using the APISIX Dashboard, and troubleshooting.

We will use the following echo endpoint as an example, which will return the parameters we passed.

Request

The request URL consists of these components:

  • Protocol: the network transport protocol, HTTP protocol is used in our example.
  • Port: The port, 80 is used in our example.
  • Host: The host, httpbin.org is used in our example.
  • Path: The path, /get is used in our example.
  • Query Parameters: the query string, two strings foo1 and foo2 are listed in our example.

Run the following command to send the request:

curl --location --request GET "http://httpbin.org/get?foo1=bar1&foo2=bar2"

Response

{
  "args": {
    "foo1": "bar1",
    "foo2": "bar2"
  },
  "headers": {
    "Accept": "*/*",
    "Host": "httpbin.org",
    "User-Agent": "curl/7.29.0",
    "X-Amzn-Trace-Id": "Root=1-6088fe84-24f39487166cce1f0e41efc9"
  },
  "origin": "58.152.81.42",
  "url": "http://httpbin.org/get?foo1=bar1&foo2=bar2"
}

Pre-requisites#

Note

If you already have Apache APISIX installed, please skip Step 1, and go to Step 2 directly.

Step 1: Install Apache APISIX#

Thanks to Docker, we can start Apache APISIX and enable it by enabling Admin API.

# Download the Docker image of Apache APISIX
git clone https://github.com/apache/apisix-docker.git
# Switch the current directory to the apisix-docker/example path
cd apisix-docker/example
# Run the docker-compose command to install Apache APISIX
docker-compose -p docker-apisix up -d

Apache APISIX has already supported ARM64 architecture. For ARM64 users, please use docker-compose -p docker-apisix -f docker-compose-arm64.yml up -d instead in the last step.

It will take some time to download all required files, please be patient.

Once the download is complete, execute the curl command on the host running Docker to access the Admin API, and determine if Apache APISIX was successfully started based on the returned data.

# Note: Please execute the curl command on the host where you are running Docker.
curl "http://127.0.0.1:9080/apisix/admin/services/" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'

The following data is returned to indicate that Apache APISIX was successfully started:

{
  "count":1,
  "action":"get",
  "node":{
    "key":"/apisix/services",
    "nodes":{},
    "dir":true
  }
}

Step 2: Create a Route#

Now we have a running instance of Apache APISIX! Next, let's create a Route.

How it works#

Apache APISIX provides users with a powerful Admin API and APISIX Dashboard. In this article, we use the Admin API to walk you through the procedures of creating a Route.

We can create a Route and connect it to an Upstream service(also known as the Upstream). When a Request arrives at Apache APISIX, Apache APISIX knows which Upstream the request should be forwarded to.

Because we have configured matching rules for the Route object, Apache APISIX can forward the request to the corresponding Upstream service. The following code creates a sample configuration of Route:

curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
  "methods": ["GET"],
  "host": "example.com",
  "uri": "/anything/*",
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

This routing configuration means that all matching inbound requests will be forwarded to the Upstream service httpbin.org:80 when they meet all the rules listed below:

  • The HTTP method of the request is GET.
  • The request header contains the host field, and its value is example.com.
  • The request path matches /anything/*, * means any subpath, for example /anything/foo?arg=10.

Once this route is created, we can access the Upstream service using the address exposed by Apache APISIX.

curl -i -X GET "http://127.0.0.1:9080/anything/foo?arg=10" -H "Host: example.com"

This will be forwarded to http://httpbin.org:80/anything/foo?arg=10 by Apache APISIX.

Create an Upstream#

After reading the previous section, we know that we must set up an Upstream for the Route. An Upstream can be created by simply executing the following command:

curl "http://127.0.0.1:9080/apisix/admin/upstreams/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
  "type": "roundrobin",
  "nodes": {
    "httpbin.org:80": 1
  }
}'

We use roundrobin as the load balancing mechanism, and set httpbin.org:80 as our upstream target (Upstream service) with an ID of 1. For more information on the fields, see Admin API.

Note

Creating an Upstream service is not actually necessary, as we can use Plugin to intercept the request and then respond directly. However, for the purposes of this guide, we assume that at least one Upstream service needs to be set up.

Bind the Route to the Upstream#

We've just created an Upstream service (referencing our backend service), now let's bind a Route for it!

curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
  "uri": "/get",
  "host": "httpbin.org",
  "upstream_id": "1"
}'

Step 3: Validation#

We have created the route and the Upstream service and bound them. Now let's access Apache APISIX to test this route.

curl -i -X GET "http://127.0.0.1:9080/get?foo1=bar1&foo2=bar2" -H "Host: httpbin.org"

It returns data from our Upstream service (actually httpbin.org) and the result is as expected.

Advanced Operations#

This section provides some advanced operations such as adding authentication, prefixing Route, using the APISIX Dashboard, and troubleshooting.

Add Authentication#

The route we created in step 2 is public. Thus, anyone can access this Upstream service as long as they know the address that Apache APISIX exposes to the outside world. This is unsafe, it creates certain security risks. In a practical application scenario, we need to add authentication to the route.

Now we want only a specific user John to have access to this Upstream service, and we need to use Consumer and Plugin to implement authentication.

First, let's use key-auth plugin to create a Consumer John, we need to provide a specified key.

curl "http://127.0.0.1:9080/apisix/admin/consumers" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
  "username": "john",
  "plugins": {
    "key-auth": {
      "key": "key-of-john"
    }
  }
}'

Next, let's bind consumer (John) to the route, we just need to enable the key-auth plugin.

curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
  "uri": "/get",
  "host": "httpbin.org",
  "plugins": {
    "key-auth": {}
  },
  "upstream_id": "1"
}'

Now when we access the route created in step 2, an Unauthorized Error will be triggered.

The correct way to access that route is to add a Header named apikey with the correct key, as shown in the code below:

curl -i -X GET http://127.0.0.1:9080/get -H "Host: httpbin.org" -H "apikey: key-of-john"

Prefixing a Route#

Now, suppose you want to add a prefix to a route (e.g. samplePrefix) and don't want to use the host header, then you can use the proxy-rewrite plugin to do so.

curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
  "uri": "/samplePrefix/get",
  "plugins": {
    "proxy-rewrite": {
      "regex_uri": ["^/samplePrefix/get(.*)", "/get$1"]
    },
    "key-auth": {}
  },
  "upstream_id": "1"
}'

You can now use the following command to invoke the route:

curl -i -X GET "http://127.0.0.1:9080/samplePrefix/get?param1=foo&param2=bar" -H "apikey: key-of-john"

APISIX Dashboard#

Apache APISIX provides a Dashboard to make our operation more intuitive and easier.

Troubleshooting#

  • Make sure that all required ports (default 9080/9443/2379) are not used by other systems or processes.

    The following are commands to terminate a process that is listening on a specific port (on unix-based systems).

    sudo fuser -k 9443/tcp

  • If the Docker container keeps restarting or failing, log in to the container and observe the logs to diagnose the problem.

    docker logs -f --tail container_id