Admin API

Description

The Admin API lets users control their deployed Apache APISIX instance. The architecture design gives an idea about how everything fits together.

Configuration

When APISIX is started, the Admin API will listen on port 9180 by default and take the API prefixed with /apisix/admin.

Therefore, to avoid conflicts between your designed API and /apisix/admin, you can modify the configuration file /conf/config.yaml to modify the default listening port.

APISIX supports setting the IP access allowlist of Admin API to prevent APISIX from being illegally accessed and attacked. You can configure the IP addresses to allow access in the deployment.admin.allow_admin option in the ./conf/config.yaml file.

The X-API-KEY shown below refers to the deployment.admin.admin_key.key in the ./conf/config.yaml file, which is the access token for the Admin API.

deployment:
    admin:
        admin_key:
        - name: admin
            key: your-admin-key  # set a secure Admin API key; if left empty, APISIX will generate one during initialization and write it back to this file
            role: admin
        allow_admin:                    # http://nginx.org/en/docs/http/ngx_http_access_module.html#allow
            - 127.0.0.0/24
        admin_listen:
            ip: 0.0.0.0                 # Specific IP, if not set, the default value is `0.0.0.0`.
            port: 9180                  # Specific port, which must be different from node_listen's port.

Using environment variables

To configure via environment variables, you can use the ${{VAR}} syntax. For instance:

deployment:
  admin:
    admin_key:
    - name: admin
      key: ${{ADMIN_KEY}}
      role: admin
    allow_admin:
    - 127.0.0.0/24
    admin_listen:
      ip: 0.0.0.0
      port: 9180

And then run export ADMIN_KEY=$your_admin_key before running make init.

If the configured environment variable can’t be found, an error will be thrown.

If you want to use a default value when the environment variable is not set, use ${{VAR:=default_value}} instead. For instance:

deployment:
  admin:
    admin_key:
    - name: admin
      key: ${{ADMIN_KEY:=your-admin-key}}
      role: admin
    allow_admin:
    - 127.0.0.0/24
    admin_listen:
      ip: 0.0.0.0
      port: 9180

This will find the environment variable ADMIN_KEY first, and if it does not exist, it will use the fallback value you provided in the configuration.

You can also specify environment variables in yaml keys. This is specifically useful in the standalone mode where you can specify the upstream nodes as follows:

routes:
  -
    uri: "/test"
    upstream:
      nodes:
        "${{HOST_IP}}:${{PORT}}": 1
      type: roundrobin
#END

Force Delete

By default, the Admin API checks for references between resources and will refuse to delete resources in use.

You can make a force deletion by adding the request argument force=true to the delete request, for example:

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

$ curl http://127.0.0.1:9180/apisix/admin/upstreams/1 -H "X-API-KEY: $admin_key" -X PUT -d '{
    "nodes": {
        "127.0.0.1:8080": 1
    },
    "type": "roundrobin"
}'
$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '{
    "uri": "/*",
    "upstream_id": 1
}'
{"value":{"priority":0,"upstream_id":1,"uri":"/*","create_time":1689038794,"id":"1","status":1,"update_time":1689038916},"key":"/apisix/routes/1"}

$ curl http://127.0.0.1:9180/apisix/admin/upstreams/1 -H "X-API-KEY: $admin_key" -X DELETE
{"error_msg":"can not delete this upstream, route [1] is still using it now"}
$ curl "http://127.0.0.1:9180/apisix/admin/upstreams/1?force=anyvalue" -H "X-API-KEY: $admin_key" -X DELETE
{"error_msg":"can not delete this upstream, route [1] is still using it now"}
$ curl "http://127.0.0.1:9180/apisix/admin/upstreams/1?force=true" -H "X-API-KEY: $admin_key" -X DELETE
{"deleted":"1","key":"/apisix/upstreams/1"}

V3 new feature

The Admin API has made some breaking changes in V3 version, as well as supporting additional features.

Support new response body format

1. Remove action field in response body;
2. Adjust the response body structure when fetching the list of resources, the new response body structure like:

Return single resource:

{
  "modifiedIndex": 2685183,
  "value": {
    "id": "1",
    ...
  },
  "key": "/apisix/routes/1",
  "createdIndex": 2684956
}

Return multiple resources:

{
  "list": [
    {
      "modifiedIndex": 2685183,
      "value": {
        "id": "1",
        ...
      },
      "key": "/apisix/routes/1",
      "createdIndex": 2684956
    },
    {
      "modifiedIndex": 2685163,
      "value": {
        "id": "2",
        ...
      },
      "key": "/apisix/routes/2",
      "createdIndex": 2685163
    }
  ],
  "total": 2
}

Support paging query

Paging query is supported when getting the resource list, paging parameters include:

The example is as follows:

curl "http://127.0.0.1:9180/apisix/admin/routes?page=1&page_size=10" \
-H "X-API-KEY: $admin_key" -X GET

{
  "total": 1,
  "list": [
    {
      ...
    }
  ]
}

Resources that support paging queries:

• Consumer
• Consumer Group
• Global Rules
• Plugin Config
• Proto
• Route
• Service
• SSL
• Stream Route
• Upstream
• Secret

Support filtering query

When getting a list of resources, it supports filtering resources based on name, label, uri.

The following example will return a list of routes, and all routes in the list satisfy: the name of the route contains the string “test”, the uri contains the string “foo”, and there is no restriction on the label of the route, since the label of the query is the empty string.

curl 'http://127.0.0.1:9180/apisix/admin/routes?name=test&uri=foo&label=' \
-H "X-API-KEY: $admin_key" -X GET

{
  "total": 1,
  "list": [
    {
      ...
    }
  ]
}

Support reference filtering query

When getting a list of resources, it supports a filter for filtering resources by filters.

It is encoded in the following manner.

filter=escape_uri(key1=value1&key2=value2)

The following example filters routes using service_id. Applying multiple filters simultaneously will return results that match all filter conditions.

curl 'http://127.0.0.1:9180/apisix/admin/routes?filter=service_id%3D1' \
-H "X-API-KEY: $admin_key" -X GET

{
  "total": 1,
  "list": [
    {
      ...
    }
  ]
}

Route

Routes match the client’s request based on defined rules, loads and executes the corresponding plugins, and forwards the request to the specified Upstream.

Route API

Route resource request address: /apisix/admin/routes/{id}?ttl=0

Quick Note on ID Syntax

ID’s as a text string must be of a length between 1 and 64 characters and they should only contain uppercase, lowercase, numbers and no special characters apart from dashes ( - ), periods ( . ) and underscores ( _ ). For integer values they simply must have a minimum character count of 1.

Request Methods

URI Request Parameters

Request Body Parameters

Example configuration:

{
    "id": "1",                            # id, unnecessary.
    "uris": ["/a","/b"],                  # A set of uri.
    "methods": ["GET","POST"],            # Can fill multiple methods
    "hosts": ["a.com","b.com"],           # A set of host.
    "plugins": {},                        # Bound plugin
    "priority": 0,                        # If different routes contain the same `uri`, determine which route is matched first based on the attribute` priority`, the default value is 0.
    "name": "route-xxx",
    "desc": "hello world",
    "remote_addrs": ["127.0.0.1"],        # A set of Client IP.
    "vars": [["http_user", "==", "ios"]], # A list of one or more `[var, operator, val]` elements
    "upstream_id": "1",                   # upstream id, recommended
    "upstream": {},                       # upstream, not recommended
    "timeout": {                          # Set the upstream timeout for connecting, sending and receiving messages of the route.
        "connect": 3,
        "send": 3,
        "read": 3
    },
    "filter_func": ""                     # User-defined filtering function
}

Example API usage

• Create a route

  curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -i -d '
  {
      "uri": "/index.html",
      "hosts": ["foo.com", "*.bar.com"],
      "remote_addrs": ["127.0.0.0/8"],
      "methods": ["PUT", "GET"],
      "enable_websocket": true,
      "upstream": {
          "type": "roundrobin",
          "nodes": {
              "127.0.0.1:1980": 1
          }
      }
  }'

  HTTP/1.1 201 Created
  Date: Sat, 31 Aug 2019 01:17:15 GMT
  ...

• Create a route expires after 60 seconds, then it’s deleted automatically

  curl 'http://127.0.0.1:9180/apisix/admin/routes/2?ttl=60' \
  -H "X-API-KEY: $admin_key" -X PUT -i -d '
  {
      "uri": "/aa/index.html",
      "upstream": {
          "type": "roundrobin",
          "nodes": {
              "127.0.0.1:1980": 1
          }
      }
  }'

  HTTP/1.1 201 Created
  Date: Sat, 31 Aug 2019 01:17:15 GMT
  ...

• Add an upstream node to the Route

  curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: $admin_key" -X PATCH -i -d '
  {
      "upstream": {
          "nodes": {
              "127.0.0.1:1981": 1
          }
      }
  }'

  HTTP/1.1 200 OK
  ...

  After successful execution, upstream nodes will be updated to:

  {
      "127.0.0.1:1980": 1,
      "127.0.0.1:1981": 1
  }

• Update the weight of an upstream node to the Route

  curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: $admin_key" -X PATCH -i -d '
  {
      "upstream": {
          "nodes": {
              "127.0.0.1:1981": 10
          }
      }
  }'

  HTTP/1.1 200 OK
  ...

  After successful execution, upstream nodes will be updated to:

  {
      "127.0.0.1:1980": 1,
      "127.0.0.1:1981": 10
  }

• Delete an upstream node for the Route

  curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: $admin_key" -X PATCH -i -d '
  {
      "upstream": {
          "nodes": {
              "127.0.0.1:1980": null
          }
      }
  }'

  HTTP/1.1 200 OK
  ...

  After successful execution, upstream nodes will be updated to:

  {
      "127.0.0.1:1981": 10
  }

• Replace methods of the Route — array

  curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: $admin_key" -X PATCH -i -d '{
      "methods": ["GET", "POST"]
  }'

  HTTP/1.1 200 OK
  ...

  After successful execution, methods will not retain the original data, and the entire update is:

  ["GET", "POST"]

• Replace upstream nodes of the Route — sub path

  curl http://127.0.0.1:9180/apisix/admin/routes/1/upstream/nodes \
  -H "X-API-KEY: $admin_key" -X PATCH -i -d '
  {
      "127.0.0.1:1982": 1
  }'

  HTTP/1.1 200 OK
  ...

  After successful execution, nodes will not retain the original data, and the entire update is:

  {
      "127.0.0.1:1982": 1
  }

• Replace methods of the Route — sub path

  curl http://127.0.0.1:9180/apisix/admin/routes/1/methods \
  -H "X-API-KEY: $admin_key" -X PATCH -i -d'["POST", "DELETE", " PATCH"]'

  HTTP/1.1 200 OK
  ...

  After successful execution, methods will not retain the original data, and the entire update is:

  ["POST", "DELETE", "PATCH"]

• Disable route

  curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: $admin_key" -X PATCH -i -d '
  {
      "status": 0
  }'

  HTTP/1.1 200 OK
  ...

  After successful execution, status nodes will be updated to:

  {
      "status": 0
  }

• Enable route

  curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: $admin_key" -X PATCH -i -d '
  {
      "status": 1
  }'

  HTTP/1.1 200 OK
  ...

  After successful execution, status nodes will be updated to:

  {
      "status": 1
  }

Response Parameters

Currently, the response is returned from etcd.

Service

A Service is an abstraction of an API (which can also be understood as a set of Route abstractions). It usually corresponds to an upstream service abstraction.

The relationship between Routes and a Service is usually N

Service API

Service resource request address: /apisix/admin/services/{id}

Request Methods

Request Body Parameters

Example configuration:

{
    "id": "1",                # id
    "plugins": {},            # Bound plugin
    "upstream_id": "1",       # upstream id, recommended
    "upstream": {},           # upstream, not recommended
    "name": "service-test",
    "desc": "hello world",
    "enable_websocket": true,
    "hosts": ["foo.com"]
}

Example API usage

• Create a service

  curl http://127.0.0.1:9180/apisix/admin/services/201  \
  -H "X-API-KEY: $admin_key" -X PUT -i -d '
  {
      "plugins": {
          "limit-count": {
              "count": 2,
              "time_window": 60,
              "rejected_code": 503,
              "key": "remote_addr"
          }
      },
      "enable_websocket": true,
      "upstream": {
          "type": "roundrobin",
          "nodes": {
              "127.0.0.1:1980": 1
          }
      }
  }'

  HTTP/1.1 201 Created
  ...

• Add an upstream node to the Service

  curl http://127.0.0.1:9180/apisix/admin/services/201 \
  -H "X-API-KEY: $admin_key" -X PATCH -i -d '
  {
      "upstream": {
          "nodes": {
              "127.0.0.1:1981": 1
          }
      }
  }'

  HTTP/1.1 200 OK
  ...

  After successful execution, upstream nodes will be updated to:

  {
      "127.0.0.1:1980": 1,
      "127.0.0.1:1981": 1
  }

• Update the weight of an upstream node to the Service

  curl http://127.0.0.1:9180/apisix/admin/services/201 \
  -H'X-API-KEY: your-admin-key' -X PATCH -i -d '
  {
      "upstream": {
          "nodes": {
              "127.0.0.1:1981": 10
          }
      }
  }'

  HTTP/1.1 200 OK
  ...

  After successful execution, upstream nodes will be updated to:

  {
      "127.0.0.1:1980": 1,
      "127.0.0.1:1981": 10
  }

• Delete an upstream node for the Service

  curl http://127.0.0.1:9180/apisix/admin/services/201 \
  -H'X-API-KEY: your-admin-key' -X PATCH -i -d '
  {
      "upstream": {
          "nodes": {
              "127.0.0.1:1980": null
          }
      }
  }'

  HTTP/1.1 200 OK
  ...

  After successful execution, upstream nodes will be updated to:

  {
      "127.0.0.1:1981": 10
  }

• Replace upstream nodes of the Service

  curl http://127.0.0.1:9180/apisix/admin/services/201/upstream/nodes \
  -H'X-API-KEY: your-admin-key' -X PATCH -i -d '
  {
      "127.0.0.1:1982": 1
  }'

  HTTP/1.1 200 OK
  ...

  After successful execution, upstream nodes will not retain the original data, and the entire update is:

  {
      "127.0.0.1:1982": 1
  }

Response Parameters

Currently, the response is returned from etcd.

Consumer

Consumers are users of services and can only be used in conjunction with a user authentication system. A Consumer is identified by a username property. So, for creating a new Consumer, only the HTTP PUT method is supported.

Consumer API

Consumer resource request address: /apisix/admin/consumers/{username}

Request Methods

Request Body Parameters

Example Configuration:

{
    "plugins": {},          # Bound plugin
    "username": "name",     # Consumer name
    "desc": "hello world"   # Consumer desc
}

When bound to a Route or Service, the Authentication Plugin infers the Consumer from the request and does not require any parameters. Whereas, when it is bound to a Consumer, username, password and other information needs to be provided.

Example API usage

curl http://127.0.0.1:9180/apisix/admin/consumers  \
-H "X-API-KEY: $admin_key" -X PUT -i -d '
{
    "username": "jack",
    "plugins": {
        "key-auth": {
            "key": "auth-one"
        },
        "limit-count": {
            "count": 2,
            "time_window": 60,
            "rejected_code": 503,
            "key": "remote_addr"
        }
    }
}'

HTTP/1.1 200 OK
Date: Thu, 26 Dec 2019 08:17:49 GMT
...

{"node":{"value":{"username":"jack","plugins":{"key-auth":{"key":"auth-one"},"limit-count":{"time_window":60,"count":2,"rejected_code":503,"key":"remote_addr","policy":"local"}}},"createdIndex":64,"key":"\/apisix\/consumers\/jack","modifiedIndex":64},"prevNode":{"value":"{\"username\":\"jack\",\"plugins\":{\"key-auth\":{\"key\":\"auth-one\"},\"limit-count\":{\"time_window\":60,\"count\":2,\"rejected_code\":503,\"key\":\"remote_addr\",\"policy\":\"local\"}}}","createdIndex":63,"key":"\/apisix\/consumers\/jack","modifiedIndex":63}}

Since v2.2, we can bind multiple authentication plugins to the same consumer.

Response Parameters

Currently, the response is returned from etcd.

Credential

Credential is used to hold the authentication credentials for the Consumer. Credentials are used when multiple credentials need to be configured for a Consumer.

Credential API

Credential resource request address：/apisix/admin/consumers/{username}/credentials/{credential_id}

Request Methods

Request Body Parameters

Example Configuration:

{
    "plugins": {
      "key-auth": {
        "key": "auth-one"
      }
    },
    "desc": "hello world"
}

Example API usage

Prerequisite: Consumer jack has been created.

Create the key-auth Credential for consumer jack:

curl http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials/auth-one  \
-H "X-API-KEY: $admin_key" -X PUT -i -d '
{
    "plugins": {
        "key-auth": {
            "key": "auth-one"
        }
    }
}'

HTTP/1.1 200 OK
Date: Thu, 26 Dec 2019 08:17:49 GMT
...

{"key":"\/apisix\/consumers\/jack\/credentials\/auth-one","value":{"update_time":1666260780,"plugins":{"key-auth":{"key":"auth-one"}},"create_time":1666260780}}

Upstream

Upstream is a virtual host abstraction that performs load balancing on a given set of service nodes according to the configured rules.

An Upstream configuration can be directly bound to a Route or a Service, but the configuration in Route has a higher priority. This behavior is consistent with priority followed by the Plugin object.

Upstream API

Upstream resource request address: /apisix/admin/upstreams/{id}

For notes on ID syntax please refer to: ID Syntax

Request Methods

Request Body Parameters

In addition to the equalization algorithm selections, Upstream also supports passive health check and retry for the upstream. See the table below for more details:

An Upstream can be one of the following types:

• roundrobin: Round robin balancing with weights.
• chash: Consistent hash.
• ewma: Pick the node with minimum latency. See EWMA Chart for more details.
• least_conn: Picks the node with the lowest value of (active_conn + 1) / weight. Here, an active connection is a connection being used by the request and is similar to the concept in Nginx.
• user-defined load balancer loaded via require("apisix.balancer.your_balancer").

The following should be considered when setting the hash_on value:

• When set to vars, a key is required. The value of the key can be any of the Nginx variables without the $ prefix.
• When set to header, a key is required. This is equal to “http_key”.
• When set to cookie, a key is required. This key is equal to “cookie_key”. The cookie name is case-sensitive.
• When set to consumer, the key is optional and the key is set to the consumer_name captured from the authentication Plugin.
• When set to vars_combinations, the key is required. The value of the key can be a combination of any of the Nginx variables like $request_uri$remote_addr.

APISIX supports proxying WebSocket connections in two different ways, and they don’t combine:

• Route or Service level enable_websocket with an http/https Upstream scheme. This is a plain protocol upgrade: nginx’s own proxy_pass forwards the raw TCP stream after the 101 Switching Protocols handshake, and no plugin phase sees the individual WebSocket frames.
• Upstream scheme: ws or scheme: wss. APISIX parses and proxies the WebSocket frames itself in both directions, which lets a plugin inspect or rewrite frames in flight through the ws_handshake, ws_client_frame, ws_upstream_frame, and ws_close phases. See the “extra phase” section of the plugin development guide for how to hook into them. enable_websocket is ignored on a Route or a Service whose Upstream uses this scheme, since the connection never reaches the proxy_pass path it configures.

The features described below requires APISIX to be run on APISIX-Runtime:

You can set the scheme to tls, which means “TLS over TCP”.

To use mTLS to communicate with Upstream, you can use the tls.client_cert/key in the same format as SSL’s cert and key fields.

Or you can reference SSL object by tls.client_cert_id to set SSL cert and key. The SSL object can be referenced only if the type field is client, otherwise the request will be rejected by APISIX. In addition, only cert and key will be used in the SSL object.

To verify the certificate presented by the Upstream, set tls.verify to true. Leaving it unset keeps the behaviour configured in nginx, which is off unless proxy_ssl_verify is turned on. The certificate is checked against the CA certificates in tls.ca_certs, or against ssl_trusted_certificate from config.yaml when tls.ca_certs is not set:

{
  "scheme": "https",
  "type": "roundrobin",
  "nodes": {
    "127.0.0.1:8443": 1
  },
  "tls": {
    "verify": true,
    "ca_certs": ["<content of ca.crt>"]
  }
}

To allow Upstream to have a separate connection pool, use keepalive_pool. It can be configured by modifying its child fields.

warm_up_conf enables slow start for the nodes of a roundrobin Upstream. Whether a node is new is decided by the gateway itself, from the node set it observes, and the start of each ramp is recorded locally in the upstream-slow-start shared dict:

• The node set an Upstream has when the gateway first builds a load balancer for it is treated as warmed up. So is the node set it already has when warm_up_conf is turned on.
• A node added afterwards ramps from min_weight_percent back to its configured weight over slow_start_time_seconds. A node held out of the load balancer by a health check starts its ramp when it first becomes available.
• A node that leaves the Upstream and comes back within slow_start_time_seconds resumes its ramp. One that comes back later, or that a health check kept out for longer than that, ramps again from the start.
• Every APISIX instance ramps independently, from the moment it observed the node.

warm_up_conf is only supported by roundrobin Upstreams whose nodes share a single priority, and it is rejected in the Upstreams of the traffic-split Plugin, which are rebuilt per request. Like the other Upstream fields that only apply to HTTP, it is ignored when the Upstream is used by a stream route. A ramp only shifts traffic between nodes: a single-node Upstream, or one whose nodes are all new, keeps sending every request to them.

Example Configuration:

{
    "id": "1",                  # id
    "retries": 1,               # retry times
    "timeout": {                # Set the timeout for connecting, sending and receiving messages, each is 15 seconds.
        "connect":15,
        "send":15,
        "read":15
    },
    "nodes": {"host:80": 100},  # Upstream machine address list, the format is `Address + Port`
                                # is the same as "nodes": [ {"host": "host", "port": 80, "weight": 100} ],
    "type":"roundrobin",
    "checks": {},               # Health check parameters
    "hash_on": "",
    "key": "",
    "name": "upstream-for-test",
    "desc": "hello world",
    "scheme": "http"            # The scheme used when communicating with upstream, the default is `http`
}

Example API usage

Create an Upstream and modify the data in nodes

1. Create upstream

   curl http://127.0.0.1:9180/apisix/admin/upstreams/100  \
   -H "X-API-KEY: $admin_key" -i -X PUT -d '
   {
       "type":"roundrobin",
       "nodes":{
           "127.0.0.1:1980": 1
       }
   }'

   HTTP/1.1 201 Created
   ...

2. Add a node to the Upstream

   curl http://127.0.0.1:9180/apisix/admin/upstreams/100 \
   -H "X-API-KEY: $admin_key" -X PATCH -i -d '
   {
       "nodes": {
           "127.0.0.1:1981": 1
       }
   }'

   HTTP/1.1 200 OK
   ...

   After successful execution, nodes will be updated to:

   {
       "127.0.0.1:1980": 1,
       "127.0.0.1:1981": 1
   }

3. Update the weight of a node to the Upstream

   curl http://127.0.0.1:9180/apisix/admin/upstreams/100 \
   -H'X-API-KEY: your-admin-key' -X PATCH -i -d '
   {
       "nodes": {
           "127.0.0.1:1981": 10
       }
   }'

   HTTP/1.1 200 OK
   ...

   After successful execution, nodes will be updated to:

   {
       "127.0.0.1:1980": 1,
       "127.0.0.1:1981": 10
   }

4. Delete a node for the Upstream

   curl http://127.0.0.1:9180/apisix/admin/upstreams/100 \
   -H "X-API-KEY: $admin_key" -X PATCH -i -d '
   {
       "nodes": {
           "127.0.0.1:1980": null
       }
   }'

   HTTP/1.1 200 OK
   ...

   After successful execution, nodes will be updated to:

   {
       "127.0.0.1:1981": 10
   }

5. Replace the nodes of the Upstream

   curl http://127.0.0.1:9180/apisix/admin/upstreams/100/nodes \
   -H "X-API-KEY: $admin_key" -X PATCH -i -d '
   {
       "127.0.0.1:1982": 1
   }'

   HTTP/1.1 200 OK
   ...

   After the execution is successful, nodes will not retain the original data, and the entire update is:

   {
       "127.0.0.1:1982": 1
   }

Proxy client request to https Upstream service

1. Create a route and configure the upstream scheme as https.

   curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \
   -H "X-API-KEY: $admin_key" -X PUT -d '
   {
       "uri": "/get",
       "upstream": {
           "type": "roundrobin",
           "scheme": "https",
           "nodes": {
               "httpbin.org:443": 1
           }
       }
   }'

   After successful execution, the scheme when requesting to communicate with the upstream will be https.

2. Send a request to test.

   curl http://127.0.0.1:9080/get

   {
   "args": {},
   "headers": {
       "Accept": "*/*",
       "Host": "127.0.0.1",
       "User-Agent": "curl/7.29.0",
       "X-Amzn-Trace-Id": "Root=1-6058324a-0e898a7f04a5e95b526bb183",
       "X-Forwarded-Host": "127.0.0.1"
   },
   "origin": "127.0.0.1",
   "url": "https://127.0.0.1/get"
   }

The request is successful, meaning that the proxy Upstream https is valid.

As the default priority is 0, nodes with negative priority can be configured as a backup.

For example:

{
  "uri": "/hello",
  "upstream": {
    "type": "roundrobin",
    "nodes": [
      { "host": "127.0.0.1", "port": 1980, "weight": 2000 },
      { "host": "127.0.0.1", "port": 1981, "weight": 1, "priority": -1 }
    ],
    "checks": {
      "active": {
        "http_path": "/status",
        "healthy": {
          "interval": 1,
          "successes": 1
        },
        "unhealthy": {
          "interval": 1,
          "http_failures": 1
        }
      }
    }
  }
}

Node 127.0.0.2 will be used only after 127.0.0.1 is tried or unavailable. It can therefore act as a backup for the node 127.0.0.1.

Response Parameters

Currently, the response is returned from etcd.

SSL

SSL API

SSL resource request address: /apisix/admin/ssls/{id}

For notes on ID syntax please refer to: ID Syntax

Request Methods

Request Body Parameters

Example Configuration:

{
    "id": "1",           # id
    "cert": "cert",      # Certificate
    "key": "key",        # Private key
    "snis": ["t.com"]    # https SNI
}

See Certificate for more examples.

Global Rule

Sets Plugins which run globally. i.e these Plugins will be run before any Route/Service level Plugins.

Global Rule API

Global Rule resource request address: /apisix/admin/global_rules/{id}

Request Methods

Request Body Parameters

Consumer group

Group of Plugins which can be reused across Consumers.

Consumer group API

Consumer group resource request address: /apisix/admin/consumer_groups/{id}

Request Methods

Request Body Parameters

Plugin config

Group of Plugins which can be reused across Routes.

Plugin Config API

Plugin Config resource request address: /apisix/admin/plugin_configs/{id}

Request Methods

Request Body Parameters

Plugin Metadata

Plugin Metadata API

Plugin Metadata resource request address: /apisix/admin/plugin_metadata/{plugin_name}

Request Methods

Request Body Parameters

A JSON object defined according to the metadata_schema of the Plugin ({plugin_name}).

Example Configuration:

curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/example-plugin  \
-H "X-API-KEY: $admin_key" -i -X PUT -d '
{
    "skey": "val",
    "ikey": 1
}'

HTTP/1.1 201 Created
Date: Thu, 26 Dec 2019 04:19:34 GMT
Content-Type: text/plain

Plugin

Plugin API

Plugin resource request address: /apisix/admin/plugins/{plugin_name}

Request Methods

Request Body Parameters

The Plugin ({plugin_name}) of the data structure.

Request Arguments

The plugin can be filtered on subsystem so that the ({plugin_name}) is searched in the subsystem passed through query params.

Example API usage:

curl "http://127.0.0.1:9180/apisix/admin/plugins/list" \
-H 'X-API-KEY: your-admin-key'

["zipkin","request-id",...]

curl "http://127.0.0.1:9180/apisix/admin/plugins/key-auth?subsystem=http" -H 'X-API-KEY: your-admin-key'

{"$comment":"this is a mark for our injected plugin schema","properties":{"header":{"default":"apikey","type":"string"},"hide_credentials":{"default":false,"type":"boolean"},"_meta":{"properties":{"filter":{"type":"array","description":"filter determines whether the plugin needs to be executed at runtime"},"disable":{"type":"boolean"},"error_response":{"oneOf":[{"type":"string"},{"type":"object"}]},"priority":{"type":"integer","description":"priority of plugins by customized order"}},"type":"object"},"query":{"default":"apikey","type":"string"}},"type":"object"}

Stream Route

Route used in the Stream Proxy.

Stream Route API

Stream Route resource request address: /apisix/admin/stream_routes/{id}

Request Methods

Request Body Parameters

To learn more about filtering in stream proxies, check this document.

Secret

Secret means Secrets Management, which could use any secret manager supported, e.g. vault.

Secret API

Secret resource request address: /apisix/admin/secrets/{secretmanager}/{id}

Request Methods

Request Body Parameters

When Secret Manager is Vault

Example Configuration:

{
    "uri": "https://localhost/vault",
    "prefix": "/apisix/kv",
    "token": "343effad"
}

Example API usage:

curl -i http://127.0.0.1:9180/apisix/admin/secrets/vault/test2 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "uri": "http://xxx/get",
    "prefix" : "apisix",
    "token" : "apisix"
}'

HTTP/1.1 200 OK
...

{"key":"\/apisix\/secrets\/vault\/test2","value":{"id":"vault\/test2","token":"apisix","prefix":"apisix","update_time":1669625828,"create_time":1669625828,"uri":"http:\/\/xxx\/get"}}

When Secret Manager is AWS

Example Configuration:

{
    "endpoint_url": "http://127.0.0.1:4566",
    "region": "us-east-1",
    "access_key_id": "access",
    "secret_access_key": "secret",
    "session_token": "token"
}

Example API usage:

curl -i http://127.0.0.1:9180/apisix/admin/secrets/aws/test3 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "endpoint_url": "http://127.0.0.1:4566",
    "region": "us-east-1",
    "access_key_id": "access",
    "secret_access_key": "secret",
    "session_token": "token"
}'

HTTP/1.1 200 OK
...

{"value":{"create_time":1726069970,"endpoint_url":"http://127.0.0.1:4566","region":"us-east-1","access_key_id":"access","secret_access_key":"secret","id":"aws/test3","update_time":1726069970,"session_token":"token"},"key":"/apisix/secrets/aws/test3"}

When Secret Manager is GCP

Example Configuration:

{
    "auth_config" : {
        "client_email": "email@apisix.iam.gserviceaccount.com",
        "private_key": "private_key",
        "project_id": "apisix-project",
        "token_uri": "https://oauth2.googleapis.com/token",
        "entries_uri": "https://secretmanager.googleapis.com/v1",
        "scope": ["https://www.googleapis.com/auth/cloud-platform"]
    }
}

Example API usage:

curl -i http://127.0.0.1:9180/apisix/admin/secrets/gcp/test4 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "auth_config" : {
        "client_email": "email@apisix.iam.gserviceaccount.com",
        "private_key": "private_key",
        "project_id": "apisix-project",
        "token_uri": "https://oauth2.googleapis.com/token",
        "entries_uri": "https://secretmanager.googleapis.com/v1",
        "scope": ["https://www.googleapis.com/auth/cloud-platform"]
    }
}'

HTTP/1.1 200 OK
...

{"value":{"id":"gcp/test4","ssl_verify":true,"auth_config":{"token_uri":"https://oauth2.googleapis.com/token","scope":["https://www.googleapis.com/auth/cloud-platform"],"entries_uri":"https://secretmanager.googleapis.com/v1","client_email":"email@apisix.iam.gserviceaccount.com","private_key":"private_key","project_id":"apisix-project"},"create_time":1726070161,"update_time":1726070161},"key":"/apisix/secrets/gcp/test4"}

Response Parameters

Currently, the response is returned from etcd.

Proto

Proto is used to store protocol buffers so that APISIX can communicate in gRPC.

See grpc-transcode plugin doc for more examples.

Proto API

Proto resource request address: /apisix/admin/protos/{id}

Request Methods

Request Body Parameters

Schema validation

Check the validity of a configuration against its entity schema. This allows you to test your input before submitting a request to the entity endpoints of the Admin API.

Note that this only performs the schema validation checks, checking that the input configuration is well-formed. Requests to the entity endpoint using the given configuration may still fail due to other reasons, such as invalid foreign key relationships or uniqueness check failures against the contents of the data store.

Schema validation

Schema validation request address: /apisix/admin/schema/validate/{resource}

Request Methods

Request Body Parameters

• 200: validate ok.
• 400: validate failed, with error as response body in JSON format.

Example:

curl http://127.0.0.1:9180/apisix/admin/schema/validate/routes \
    -H "X-API-KEY: $admin_key" -X POST -i -d '{
    "uri": 1980,
    "upstream": {
        "scheme": "https",
        "type": "roundrobin",
        "nodes": {
            "nghttp2.org": 1
        }
    }
}'
HTTP/1.1 400 Bad Request
Date: Mon, 21 Aug 2023 07:37:13 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/3.4.0
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: *
Access-Control-Max-Age: 3600

{"error_msg":"property \"uri\" validation failed: wrong type: expected string, got number"}