Apache APISIX is a high-performance cloud native API gateway.

An API gateway typically sits between your client applications and your APIs, acting as a proxy while adding authentication, traffic control, monitoring, and other capabilities.

This interactive playground walks you through configuring Apache APISIX, directly in your browser.

Note: This playground uses a lightweight APISIX sandbox, and its performance might be (it is) sub-par compared to typical production setups. Please refer to the APISIX in Production guides to learn more about practical APISIX deployments.

Install APISIX

The easiest way to get up and running with Apache APISIX is through Docker. APISIX provides official Docker images which are easy to configure and run.

For this walkthrough, we have deployed APISIX in standalone mode and will configure it through a YAML file. Unlike a traditional or a decoupled deployment, the standalone mode does not require managing external dependencies like etcd for configuration.

Let’s check if everything is installed correctly by running:

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

The Server header should have the value APISIX.

Create Routes

Routes are the fundamental building blocks of APISIX. A route matches client requests by conditions and forwards them to the appropriate upstream service.

Let’s create a simple route that matches requests based on the path and forwards them to a public HTTP API, httpbin.org:

routes:
  - id: playground-ip
    uri: /ip
    upstream:
      nodes:
        httpbin.org:80: 1
      type: roundrobin
#END

This configuration is pretty straightforward: if a request path matches /ip, proxy the request to the httpbin.org upstream.

To test our configuration, we can send a request to the /ip path as shown below:

curl "http://127.0.0.1:9080/ip"

You will see your IP address in the response.

If you try to access an invalid route, you will receive a 404 Not Found error:

curl "http://127.0.0.1:9080/anything"

Configure Load Balancing

We can’t let a single upstream handle all the load, can we? Well, we shouldn’t.

Let’s add another upstream node, mock.api7.ai, and use APISIX’s load balancing capabilities to distribute requests among them:

routes:
  - id: playground-headers
    uri: /headers
    upstream:
      nodes:
        httpbin.org:443: 1
        mock.api7.ai:443: 1
      type: roundrobin
      pass_host: node
      scheme: https
#END

We also configure APISIX to use the round-robin algorithm for load balancing and set up HTTPS between APISIX and the upstream.

Now try sending requests to the created route by running the command below multiple times. You will see that the requests are load balanced between the two upstreams:

curl "http://127.0.0.1:9080/headers"

Did you notice how we passed the Host header to the upstream?

Add Authentication

Until now, all of our requests were unauthenticated, which is rare in almost all practical scenarios. So, let’s fix that.

APISIX uses plugins to extend its capabilities and add features. It comes with many authentication plugins out of the box.

We will add the simple but widely used key-auth plugin to our setup. This basically forces your API consumers to authenticate their requests with a predetermined key.

Let’s start by defining a consumer who would consume our API:

1consumers:
2  - username: Nicolas
3    plugins:
4      key-auth:
5        key: sUpEr-seCRet-keY

The consumer has a key that he can use to send requests.

Let’s update our route to look for this key before accepting a request:

 6routes:
 7  - id: playground-ip
 8    uri: /ip
 9    upstream:
10      nodes:
11        httpbin.org:80: 1
12      type: roundrobin
13    plugins:
14      key-auth: {}
15#END

We just have to enable the plugin on a route for it to take effect.

Now, a user will only be able to make a successful request if he has the key:

curl "http://127.0.0.1:9080/ip" -H 'apikey: sUpEr-seCRet-keY'

Try removing the key or changing it to an invalid value before sending a request. Did it work as you expected?

Set Up Rate Limits

Finally, you must ensure that your consumers don’t take advantage of your generosity by recklessly consuming your APIs. How do you do this?

You can always talk to your consumers, but a better way is to configure APISIX to set these limits.

APISIX comes with three plugins for configuring rate limits: limit-req, limit-conn, and limit-count. We will use the limit-count plugin to limit the number of requests a consumer can make in 10 seconds (very arbitrary):

routes:
  - id: playground-ip
    uri: /ip
    upstream:
      nodes:
        httpbin.org:80: 1
      type: roundrobin
    plugins:
      limit-count:
        count: 2
        time_window: 10
        rejected_code: 429
#END

APISIX will block subsequent requests from consumers if they exceed the limit (2) in the given time window (10s) with a 429 Too Many Requests status code.

But this is better if we try it. Let’s send four requests instead of the limit of two:

curl "http://127.0.0.1:9080/ip"
curl "http://127.0.0.1:9080/ip"
curl "http://127.0.0.1:9080/ip"
curl "http://127.0.0.1:9080/ip"

What happens when we reach the limit?

Have Fun!

That’s it for the walkthrough! For more complex configurations and practical scenarios, check out other tutorials.

Meanwhile, here’s a blank canvas to play around with the concepts you learned from this walkthrough:

routes:
  - id: playground-anything
    uri: /anything/*
    upstream:
      nodes:
        httpbin.org:80: 1
      type: roundrobin
#END

curl "http://127.0.0.1:9080/anything/fun"

This playground is powered by Codapi. A huge thank you to its creator, Anton Zhiyanov.