Tutorial: Proxying and Managing API Requests via Plugins

This tutorial builds on the Quick Start and walks you through a realistic scenario: proxying API requests through API7 Gateway while applying authentication and rate limiting using plugins.

What you will learn:

1. Create a service and route for a backend API
2. Add the key-auth plugin to require API key authentication
3. Create a consumer with credentials
4. Add the limit-count plugin to enforce rate limits
5. Test the complete setup

Time to complete: ~15 minutes

Prerequisites: A running API7 Gateway instance. If you have not set one up yet, complete the Quick Start first. If you want to follow the Admin API examples, obtain a token from the Dashboard before you begin.

Step 1: Create a Service and Route

Create a service that proxies to the httpbin.org service:

Dashboard

1. In the Dashboard sidebar, navigate to the default gateway group and click Services.
2. Click Add Service, then Add Manually.
3. Configure the service:

Field	Value
Name	demo-api
Service Type	HTTP (Layer 7 Proxy)
Upstream Scheme	HTTP
How to find the upstream	Use Nodes

4. Click Add Node and configure:

Field	Value
Host	httpbin.org
Port	80
Weight	100

5. Click Add to create the service.
6. Click the demo-api service, then click Add Route.
7. Configure the route:

Field	Value
Name	get-request
Path	/get
Methods	GET

8. Click Add.

Admin API

# Create the service with the upstream
curl -k "https://localhost:7443/apisix/admin/services/demo-api?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "demo-api",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        { "host": "httpbin.org", "port": 80, "weight": 100 }
      ]
    }
  }'

# Create the route under that service
curl -k "https://localhost:7443/apisix/admin/routes/get-request?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get-request",
    "service_id": "demo-api",
    "paths": ["/get"],
    "methods": ["GET"]
  }'

If you are not running locally, replace localhost with your Admin API host. The -k flag is required if the Admin API uses a self-signed TLS certificate. Replace {gateway_group_id} with the gateway group ID — use default for the gateway group created by the quickstart, or copy the ID from the Gateway Groups page in the Dashboard.

ADC

adc.yaml

services:
  - name: demo-api
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - name: get-request
        uris:
          - /get
        methods:
          - GET

adc sync -f adc.yaml

Step 2: Verify the Proxy

Test the route to validate the basic setup before adding plugins:

curl -i "http://localhost:9080/get"

You should receive a 200 OK response with the HTTPBin response body, confirming the proxy works.

Step 3: Enable Key Auth Plugin

The key-auth plugin requires consumers to provide a valid API key.

Dashboard

1. In the default gateway group, navigate to Services and click the demo-api service.
2. Click Plugins, then Enable Plugin.
3. Search for key-auth and enable it.
4. Use the default configuration and click Submit.

Admin API

# Replace the service definition with key-auth enabled
curl -k "https://localhost:7443/apisix/admin/services/demo-api?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "demo-api",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        { "host": "httpbin.org", "port": 80, "weight": 100 }
      ]
    },
    "plugins": {
      "key-auth": {}
    }
  }'

ADC

adc.yaml

services:
  - name: demo-api
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - name: get-request
        uris:
          - /get
        methods:
          - GET
    plugins:
      key-auth: {}

adc sync declaratively replaces all resources, so the file must contain the full desired state — keep the upstream and route blocks from Step 1 alongside the new plugins block.

adc sync -f adc.yaml

Test Without a Key

curl -i "http://localhost:9080/get"

Expected response:

HTTP/1.1 401 Unauthorized
{"message":"Missing API key in request"}

Step 4: Create a Consumer

Create a consumer with an API key credential:

Dashboard

1. In the Dashboard sidebar, navigate to Consumers, then click Create Consumer.
2. Configure the consumer:

Field	Value
Name	test-consumer

3. Click Submit to create the consumer.
4. Click the test-consumer consumer to open it, then select the Credentials tab.
5. Click Create Credential and select key-auth as the type.
6. Configure the credential:

Field	Value
Name	test-consumer-key
Key	my-secret-api-key

7. Click Submit.

Admin API

# Create the consumer
curl -k "https://localhost:7443/apisix/admin/consumers/test-consumer?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "test-consumer"
  }'

# Add the key-auth credential to the consumer
curl -k "https://localhost:7443/apisix/admin/consumers/test-consumer/credentials/test-consumer-key?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-consumer-key",
    "plugins": {
      "key-auth": {
        "key": "my-secret-api-key"
      }
    }
  }'

On API7 Enterprise, authentication keys live on a credential resource attached to the consumer, not inline on the consumer itself. The Admin API rejects inline key-auth plugin configuration on a consumer with the error adding new key-auth plugin in consumer is not allowed, please use it in credential.

ADC

adc.yaml

consumers:
  - username: test-consumer
    credentials:
      - name: test-consumer-key
        type: key-auth
        config:
          key: my-secret-api-key

adc sync -f adc.yaml

Test With the API Key

curl -i "http://localhost:9080/get" -H "apikey: my-secret-api-key"

Expected response: 200 OK.

Step 5: Enable Rate Limiting

Add the limit-count plugin to restrict the number of requests a consumer can make.

Dashboard

1. In the default gateway group, navigate to Services and click the demo-api service.
2. Click Plugins, then Enable Plugin.
3. Search for limit-count and configure it:

{
  "count": 5,
  "time_window": 60,
  "rejected_code": 429,
  "key_type": "var",
  "key": "consumer_name",
  "policy": "local"
}

4. Click Submit.

Admin API

# Replace the service definition with key-auth and limit-count
curl -k "https://localhost:7443/apisix/admin/services/demo-api?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "demo-api",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        { "host": "httpbin.org", "port": 80, "weight": 100 }
      ]
    },
    "plugins": {
      "key-auth": {},
      "limit-count": {
        "count": 5,
        "time_window": 60,
        "rejected_code": 429,
        "key_type": "var",
        "key": "consumer_name",
        "policy": "local"
      }
    }
  }'

ADC

adc.yaml

services:
  - name: demo-api
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - name: get-request
        uris:
          - /get
        methods:
          - GET
    plugins:
      key-auth: {}
      limit-count:
        count: 5
        time_window: 60
        rejected_code: 429
        key_type: var
        key: consumer_name
        policy: local

adc sync -f adc.yaml

Test the Rate Limit

Send multiple requests in quick succession:

for i in $(seq 1 6); do
  echo "Request $i:"
  curl -s -o /dev/null -w "HTTP %{http_code}\n" \
    http://localhost:9080/get -H "apikey: my-secret-api-key"
done

Expected output:

Request 1: HTTP 200
Request 2: HTTP 200
Request 3: HTTP 200
Request 4: HTTP 200
Request 5: HTTP 200
Request 6: HTTP 429

Next Steps

• Learn More About API7 Products and APISIX: Understand the full API7 product ecosystem.
• Configure the Control Plane: Fine-tune your control plane for production.
• Monitor Gateway Metrics: Monitor your gateway traffic.