Getting started

You will learn:

• What Apache APISIX is.
• Architecture and key concepts of APISIX.
• How to install and run APISIX in Docker.
• How to create your first Route and configure an Upstream using Admin API.
• How to use APISIX dashboard.
• Where you can reach out for help.

Apache APISIX is an open source, dynamic, scalable, and high-performance cloud native API gateway for all your APIs and microservices.

APISIX facilitates interface traffic handling for websites, mobile and IoT applications by providing services such as load balancing, dynamic upstream, canary release, fine-grained routing, rate limiting, and many more.

• Multi-platform support: APISIX can run from bare-metal machines to Kubernetes providing a vendor neutral, multi-platform solution. It also provides integration to cloud services like AWS Lambda, Azure Function, Lua functions and Apache OpenWhisk.
• Fully dynamic: APISIX supports hot-reloading, meaning you don’t need to restart the service to reflect changes in the configuration.
• Fine-grained routing: APISIX supports using all built-in NGINX variables for routing. You can define custom matching functions to filter requests and match Route.
• Ops-friendly: APISIX is renowned for its ops-friendliness by DevOps teams. It integrates with tools and platforms like , Zipkin, , Consul, and Eureka. With , operators can configure APISIX through an easy-to-use and intuitive UI.
• Multi-language Plugin support: APISIX supports multiple programming languages for Plugin development. Developers can choose a language-specific SDK to write custom Plugins.

Key concepts

Here is a high-level overview of APISIX’s software architecture:

The table below defines the key concepts and components of APISIX referenced in this guide:

Before you start with APISIX, make sure you have the following tools installed:

• Docker and .
• curl for testing the API. Alternatively, you can use tools like .

The example Upstream service used here is httpbin.org and you can use it for your testing.

This is an echo service, meaning it will return back the parameters we pass in the request.

Request

The components of the request URL are shown and explained below:

• Port: The port. 80 is used for this example.
• Host: The host. httpbin.org is used for this example.
• Path: The path. /get is used for this example.
• Query Parameters: The query string. Two strings foo1 and foo2 are used for this example.

We can use the curl command to send the request:

Response

We receive a JSON response when we send the request:

{
  "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"

Install Apache APISIX

First clone the apisix-docker repository:

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

Now, you can use docker-compose to start APISIX.

• x86
• ARM/M1

docker-compose -p docker-apisix up -d

note

You can check out Installing Apache APISIX for different installation methods.

IMPORTANT

Make sure that all the required ports (default: 9080, 9443 and 2379) are available and not used by other system processes.

On Unix-based systems, you can run the command below to terminate a process listening on a specific port:

sudo fuser -k 9443/tcp

If a Docker container is crashing, you can inspect the logs to diagnose the problem:

Once APISIX is running, you can use curl to access the Admin API. You can also check if APISIX is running properly by running this command and checking the response.

curl "http://127.0.0.1:9080/apisix/admin/services/" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'

This response indicates that APISIX is running successfully:

From the previous step, we have a running instance of APISIX in Docker. Now let’s create a Route.

APISIX provides a powerful and APISIX Dashboard. Here, we will use the Admin API to create a Route and connect it to an service. When a request arrives, APISIX will forward the request to the specified Upstream service.

We will configure the Route so that APISIX can forward the request to the corresponding Upstream service:

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 configuration means that it will forward all matching inbound requests to the Upstream service (httpbin.org:80) if they meet these specified criterion:

• 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 sub path. For example /anything/foo?arg=10.

With the Route has created, we can access the Upstream service from the address exposed by APISIX:

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

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

Abstracting to Upstream

Instead of configuring the Upstream directly to the Route, you can create an Upstream object and use it in the Route.

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
  }
}'

This is the same as the Upstream service we configured directly into the Route on the previous section.

To bind this Upstream to the Route, we can use the upstream_id as 1:

With the Route has created, we can access the Upstream service from the address exposed by APISIX:

This request will be forwarded to by APISIX.

You can also use the APISIX Dashboard to create and configure Routes similar to the Admin API.

If you have followed the steps above, you would be able to access the dashboard at localhost:9000.

Click on from the sidebar to view a list of configured Routes. You would be able to see the Routes you created using the Admin API as well.

You can create a new Route through the dashboard by clicking the Create button and following the instructions:

The newly created Route is added to the list of Routes:

Check out the to learn more.

Where to go next?

If you have followed the steps above, you should have APISIX running and you would have configured a Route.

You can now look into adding Plugins to provide features like authentication, security, traffic control and observability. See the to learn more.

If you ever get stuck, you can ask for help in the APISIX community channels or on GitHub.