Skip to main content

APISIX Admin API (3.8.0)

Download OpenAPI specification:Download

APISIX Admin API is a RESTful API that allows you to create and manage APISIX resources.

Route

A route defines a path to one or more upstream services.

See Routes for more information.

Get All Routes

Get all configured routes.

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "list": [
    ]
}

Create Route

Create a route with an ID generated.

Request Body schema: application/json
Any of
desc
string <= 256 characters
string or integer
status
integer
Default: 1
Enum: 1 0

route status, 1 to enable, 0 to disable

string or integer
enable_websocket
boolean
string or integer
methods
Array of strings unique
Items Enum: "GET" "POST" "PUT" "DELETE" "PATCH" "HEAD" "OPTIONS" "CONNECT" "TRACE" "PURGE"
hosts
Array of strings non-empty unique
Array of IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) non-empty unique
filter_func
string >= 10 characters ^function
vars
Array of arrays
name
string [ 1 .. 100 ] characters
string or integer
string or integer
host
string
priority
integer
Default: 0
object or object
plugins
required
object
IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string)

client IP

object

Key-value pairs to specify attributes.

object
script
string [ 10 .. 102400 ] characters
uri
required
string [ 1 .. 4096 ] characters
uris
Array of strings non-empty unique

Responses

Request samples

Content type
application/json
{
  • "name": "route-name",
  • "desc": "desc",
  • "hosts": [
    ],
  • "methods": [
    ],
  • "uri": "/ip",
  • "upstream": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/routes/00000000000000000206"
}

Create Route by ID

Create a route with a custom ID.

path Parameters
id
required
string

The route id

Request Body schema: application/json
Any of
desc
string <= 256 characters
string or integer
status
integer
Default: 1
Enum: 1 0

route status, 1 to enable, 0 to disable

string or integer
enable_websocket
boolean
string or integer
methods
Array of strings unique
Items Enum: "GET" "POST" "PUT" "DELETE" "PATCH" "HEAD" "OPTIONS" "CONNECT" "TRACE" "PURGE"
hosts
Array of strings non-empty unique
Array of IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) non-empty unique
filter_func
string >= 10 characters ^function
vars
Array of arrays
name
string [ 1 .. 100 ] characters
string or integer
string or integer
host
string
priority
integer
Default: 0
object or object
plugins
required
object
IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string)

client IP

object

Key-value pairs to specify attributes.

object
script
string [ 10 .. 102400 ] characters
uri
required
string [ 1 .. 4096 ] characters
uris
Array of strings non-empty unique

Responses

Request samples

Content type
application/json
{
  • "name": "route-test",
  • "desc": "desc",
  • "uri": "/ip",
  • "hosts": [
    ],
  • "methods": [
    ],
  • "plugins": {
    },
  • "priority": 0,
  • "remote_addrs": [
    ],
  • "vars": [
    ],
  • "upstream": {
    },
  • "timeout": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/routes/1"
}

Get Route by ID

Get a route by ID.

path Parameters
id
required
string

The route id

Responses

Response samples

Content type
application/json
{
  • "createdIndex": 203,
  • "key": "/apisix/routes/1",
  • "value": {
    },
  • "modifiedIndex": 203
}

Update Route

Update a route.

path Parameters
id
required
string
Example: 1

The target route id

Request Body schema: application/json
Any of
desc
string <= 256 characters
string or integer
status
integer
Default: 1
Enum: 1 0

route status, 1 to enable, 0 to disable

string or integer
enable_websocket
boolean
string or integer
methods
Array of strings unique
Items Enum: "GET" "POST" "PUT" "DELETE" "PATCH" "HEAD" "OPTIONS" "CONNECT" "TRACE" "PURGE"
hosts
Array of strings non-empty unique
Array of IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) non-empty unique
filter_func
string >= 10 characters ^function
vars
Array of arrays
name
string [ 1 .. 100 ] characters
string or integer
string or integer
host
string
priority
integer
Default: 0
object or object
plugins
required
object
IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string)

client IP

object

Key-value pairs to specify attributes.

object
script
string [ 10 .. 102400 ] characters
uri
required
string [ 1 .. 4096 ] characters
uris
Array of strings non-empty unique

Responses

Request samples

Content type
application/json
{
  • "upstream": {
    }
}

Response samples

Content type
application/json
Example
{
  • "value": {
    },
  • "key": "/apisix/routes/1"
}

Delete Route by ID

Delete a route by ID.

path Parameters
id
required
string

The route id

query Parameters
force
string
Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

Content type
application/json
{
  • "deleted": "1",
  • "key": "/apisix/routes/1"
}

Upstream

An upstream is a logical abstraction of one or more upstream addresses.

See Upstreams for more information.

Get All Upstreams

Get all configured upstreams.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 2
}

Create Upstream

Create an upstream with an ID generated.

Request Body schema: application/json
One of
desc
string <= 256 characters
key
string

The key used with hash_on when type is chash. When hash_on is set to header or cookie, key is required. When hash_on is set to consumer, key is not required as the consumer name will be used as the key automatically.

retries
integer >= 0
retry_timeout
number >= 0
pass_host
string
Default: "pass"
Enum: "pass" "node" "rewrite"

Configure the host when the request is forwarded to the upstream. pass is used to pass the request's host to the upstream without modification. node sets the host to the the host of the upstream node. rewrite sets the host to the value of upstream_host.

upstream_host
string
type
string
Default: "roundrobin"
Enum: "roundrobin" "chash" "ewma" "least_conn"

Load balancing algorithm. Support weighted round robin, consistent hashing, exponentially weighted moving average, and least connections algorithms.

object or object
hash_on
string
Default: "vars"
Enum: "vars" "header" "cookie" "consumer" "vars_combinations"

Type of value to hash on when type is chash.

name
string [ 1 .. 100 ] characters
scheme
any
Default: "http"
Enum: "grpc" "grpcs" "http" "https" "tcp" "tls" "udp" "kafka"

Protocol to communicate with the upstream.

service_name
string [ 1 .. 256 ] characters
object
object
string or integer
discovery_type
string

discovery type

object

Key-value pairs to specify attributes.

object
required
object or Array of objects
object

Responses

Request samples

Content type
application/json
{
  • "name": "upstream-for-test",
  • "desc": "desc",
  • "scheme": "http",
  • "retries": 1,
  • "type": "roundrobin",
  • "nodes": {
    },
  • "timeout": {
    }
}

Response samples

Content type
application/json
{
  • "key": "/apisix/upstreams/00000000000000000128",
  • "value": {
    }
}

Update Upstream

Update an upstream.

path Parameters
id
required
string

Specified upstream ID.

Request Body schema: application/json
One of
desc
string <= 256 characters
key
string

The key used with hash_on when type is chash. When hash_on is set to header or cookie, key is required. When hash_on is set to consumer, key is not required as the consumer name will be used as the key automatically.

retries
integer >= 0
retry_timeout
number >= 0
pass_host
string
Default: "pass"
Enum: "pass" "node" "rewrite"

Configure the host when the request is forwarded to the upstream. pass is used to pass the request's host to the upstream without modification. node sets the host to the the host of the upstream node. rewrite sets the host to the value of upstream_host.

upstream_host
string
type
string
Default: "roundrobin"
Enum: "roundrobin" "chash" "ewma" "least_conn"

Load balancing algorithm. Support weighted round robin, consistent hashing, exponentially weighted moving average, and least connections algorithms.

object or object
hash_on
string
Default: "vars"
Enum: "vars" "header" "cookie" "consumer" "vars_combinations"

Type of value to hash on when type is chash.

name
string [ 1 .. 100 ] characters
scheme
any
Default: "http"
Enum: "grpc" "grpcs" "http" "https" "tcp" "tls" "udp" "kafka"

Protocol to communicate with the upstream.

service_name
string [ 1 .. 256 ] characters
object
object
string or integer
discovery_type
string

discovery type

object

Key-value pairs to specify attributes.

object
required
object or Array of objects
object

Responses

Request samples

Content type
application/json
{
  • "nodes": {
    }
}

Response samples

Content type
application/json
Example
{
  • "key": "/apisix/upstreams/1",
  • "value": {
    }
}

Get Upstream by ID

Get an upstream by ID.

path Parameters
id
required
string

Specified upstream ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/upstreams/1",
  • "modifiedIndex": 126,
  • "createdIndex": 121
}

Delete Upstream by ID

Delete an upstream by ID.

path Parameters
id
required
string

Specified upstream ID.

query Parameters
force
string
Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

Content type
application/json
{
  • "key": "/apisix/upstreams/1",
  • "deleted": "1"
}

Create an Upstream by ID

Create an upstream with a custom ID.

path Parameters
id
required
string

Specified upstream ID.

Request Body schema: application/json
One of
desc
string <= 256 characters
key
string

The key used with hash_on when type is chash. When hash_on is set to header or cookie, key is required. When hash_on is set to consumer, key is not required as the consumer name will be used as the key automatically.

retries
integer >= 0
retry_timeout
number >= 0
pass_host
string
Default: "pass"
Enum: "pass" "node" "rewrite"

Configure the host when the request is forwarded to the upstream. pass is used to pass the request's host to the upstream without modification. node sets the host to the the host of the upstream node. rewrite sets the host to the value of upstream_host.

upstream_host
string
type
string
Default: "roundrobin"
Enum: "roundrobin" "chash" "ewma" "least_conn"

Load balancing algorithm. Support weighted round robin, consistent hashing, exponentially weighted moving average, and least connections algorithms.

object or object
hash_on
string
Default: "vars"
Enum: "vars" "header" "cookie" "consumer" "vars_combinations"

Type of value to hash on when type is chash.

name
string [ 1 .. 100 ] characters
scheme
any
Default: "http"
Enum: "grpc" "grpcs" "http" "https" "tcp" "tls" "udp" "kafka"

Protocol to communicate with the upstream.

service_name
string [ 1 .. 256 ] characters
object
object
string or integer
discovery_type
string

discovery type

object

Key-value pairs to specify attributes.

object
required
object or Array of objects
object

Responses

Request samples

Content type
application/json
{
  • "name": "upstream-for-test",
  • "desc": "desc",
  • "scheme": "http",
  • "retries": 1,
  • "type": "roundrobin",
  • "nodes": {
    },
  • "timeout": {
    }
}

Response samples

Content type
application/json
Example
{
  • "key": "/apisix/upstreams/1",
  • "value": {
    }
}

Service

A service is a backend application providing a set of functionalities.

See Services for more information.

Get All Services

Get all configured services.

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "list": [
    ]
}

Create Service

Create a service with an ID generated.

Request Body schema: application/json
desc
string <= 256 characters
name
string [ 1 .. 100 ] characters
string or integer
plugins
object
object or object
labels
object

Key-value pairs to specify attributes.

enable_websocket
boolean
script
string [ 10 .. 102400 ] characters
string or integer
hosts
Array of strings non-empty unique

Responses

Request samples

Content type
application/json
{
  • "plugins": { },
  • "upstream": {
    },
  • "name": "service-test",
  • "desc": "hello world",
  • "enable_websocket": true,
  • "hosts": [
    ]
}

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/services/00000000000000000218"
}

Get Service by ID

Get a service by ID.

path Parameters
id
required
string

The target service id

Responses

Response samples

Content type
application/json
{
  • "createdIndex": 117,
  • "key": "/apisix/services/1",
  • "value": {
    },
  • "modifiedIndex": 216
}

Create Service by ID

Create a service with a custom ID.

path Parameters
id
required
string

Specifies the ID of the service resource

Request Body schema: application/json
desc
string <= 256 characters
name
string [ 1 .. 100 ] characters
string or integer
plugins
object
object or object
labels
object

Key-value pairs to specify attributes.

enable_websocket
boolean
script
string [ 10 .. 102400 ] characters
string or integer
hosts
Array of strings non-empty unique

Responses

Request samples

Content type
application/json
{
  • "plugins": {
    },
  • "upstream": {
    },
  • "name": "service-test",
  • "desc": "hello world",
  • "enable_websocket": true,
  • "hosts": [
    ]
}

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/services/1"
}

Update Service

Update a service.

path Parameters
id
required
string

The target service id

Request Body schema: application/json
desc
string <= 256 characters
name
string [ 1 .. 100 ] characters
string or integer
plugins
object
object or object
labels
object

Key-value pairs to specify attributes.

enable_websocket
boolean
script
string [ 10 .. 102400 ] characters
string or integer
hosts
Array of strings non-empty unique

Responses

Request samples

Content type
application/json
{
  • "upstream": {
    }
}

Response samples

Content type
application/json
Example
{
  • "value": {
    },
  • "key": "/apisix/services/1"
}

Delete Service by ID

Delete a service by ID.

path Parameters
id
required
string

The service id

query Parameters
force
string
Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

Content type
application/json
{
  • "deleted": "1",
  • "key": "/apisix/services/1"
}

Consumer

A consumer represents a user, application, or host that sends requests to the API gateway and consumes backend services.

See Consumers for more information.

Create Consumer

Create a consumer with a custom ID.

Request Body schema: application/json
plugins
object
username
required
string [ 1 .. 100 ] characters ^[a-zA-Z0-9_]+$
labels
object

Key-value pairs to specify attributes.

desc
string <= 256 characters
string or integer

Responses

Request samples

Content type
application/json
{
  • "username": "jack",
  • "plugins": {
    }
}

Response samples

Content type
application/json
{
  • "key": "/apisix/consumers/jack",
  • "value": {
    }
}

Get All Consumers

Get all configured consumers.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get Consumer by ID

Get a consumer by ID.

path Parameters
username
required
string

Specified consumer username.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/consumers/jack",
  • "modifiedIndex": 119,
  • "createdIndex": 17
}

Delete Consumer by ID

Delete a consumer by ID.

path Parameters
username
required
string

Specified consumer username.

query Parameters
force
string
Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

Content type
application/json
{
  • "key": "/apisix/consumers/jack",
  • "deleted": "1"
}

Consumer Group

A consumer group is a group of consumers sharing the same plugin configurations.

See Consumer Groups for more information.

Get All Consumer Group

Get all configured consumer groups.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create Consumer Group by ID

Create a consumer group with a custom ID.

path Parameters
id
required
string

Specified consumer groups ID.

Request Body schema: application/json
plugins
required
object
desc
string <= 256 characters
labels
object

Key-value pairs to specify attributes.

required
string or integer

Responses

Request samples

Content type
application/json
{
  • "desc": "desc",
  • "plugins": {
    }
}

Response samples

Content type
application/json
{
  • "key": "/apisix/consumer_groups/company_a",
  • "value": {
    }
}

Get Consumer Group by ID

Get a consumer group by ID.

path Parameters
id
required
string

Specified consumer groups ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/consumer_groups/company_a",
  • "modifiedIndex": 144,
  • "createdIndex": 143
}

Update Consumer Group

Update a consumer group.

path Parameters
id
required
string

Specified consumer group ID.

Request Body schema: application/json
plugins
required
object
desc
string <= 256 characters
labels
object

Key-value pairs to specify attributes.

required
string or integer

Responses

Request samples

Content type
application/json
{
  • "plugins": {
    }
}

Response samples

Content type
application/json
{
  • "key": "/apisix/consumer_groups/company_a",
  • "value": {
    }
}

Delete Consumer Group by ID

Delete a consumer group by ID.

path Parameters
id
required
string

Specified consumer group ID.

query Parameters
force
string
Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

Content type
application/json
{
  • "key": "/apisix/consumer_groups/company_a",
  • "deleted": "1"
}

Plugin

Plugins extend base functionalities of APISIX to meet user-specific requirements.

See Plugins for more information.

Get All Plugin Names

Get all configured plugin names.

query Parameters
subsystem
string
Default: "http"
Enum: "http" "stream"
Example: subsystem=stream

Get HTTP or Stream plugin names.

Responses

Response samples

Content type
application/json
[
  • "real-ip",
  • "ai",
  • "client-control",
  • "proxy-control",
  • "request-id",
  • "zipkin",
  • "ext-plugin-pre-req",
  • "fault-injection",
  • "mocking",
  • "serverless-pre-function",
  • "cors",
  • "ip-restriction",
  • "ua-restriction",
  • "referer-restriction",
  • "csrf",
  • "uri-blocker",
  • "request-validation",
  • "openid-connect",
  • "cas-auth",
  • "authz-casbin",
  • "authz-casdoor",
  • "wolf-rbac",
  • "ldap-auth",
  • "hmac-auth",
  • "basic-auth",
  • "jwt-auth",
  • "key-auth",
  • "consumer-restriction",
  • "forward-auth",
  • "opa",
  • "authz-keycloak",
  • "body-transformer",
  • "proxy-mirror",
  • "proxy-cache",
  • "proxy-rewrite",
  • "workflow",
  • "api-breaker",
  • "limit-conn",
  • "limit-count",
  • "limit-req",
  • "gzip",
  • "server-info",
  • "traffic-split",
  • "redirect",
  • "response-rewrite",
  • "degraphql",
  • "kafka-proxy",
  • "grpc-transcode",
  • "grpc-web",
  • "public-api",
  • "prometheus",
  • "datadog",
  • "elasticsearch-logger",
  • "echo",
  • "loggly",
  • "http-logger",
  • "splunk-hec-logging",
  • "skywalking-logger",
  • "google-cloud-logging",
  • "sls-logger",
  • "tcp-logger",
  • "kafka-logger",
  • "rocketmq-logger",
  • "syslog",
  • "udp-logger",
  • "file-logger",
  • "clickhouse-logger",
  • "tencent-cloud-cls",
  • "inspect",
  • "example-plugin",
  • "aws-lambda",
  • "azure-functions",
  • "openwhisk",
  • "openfunction",
  • "serverless-post-function",
  • "ext-plugin-post-req",
  • "ext-plugin-post-resp"
]

Get Plugin Attributes by Name

Get attributes of a plugin by plugin name.

path Parameters
plugin_name
required
string

The specified plugin name

query Parameters
subsystem
string
Default: "http"
Enum: "http" "stream"
Example: subsystem=stream

Get attributes of the specified plugin name in HTTP or Stream subsystem.

Responses

Response samples

Content type
application/json
{
  • "type": "object",
  • "then": {
    },
  • "required": [
    ],
  • "if": {
    },
  • "else": {
    },
  • "$comment": "this is a mark for our injected plugin schema",
  • "properties": {
    }
}

Get All Plugin Attributes

Get all configured plugin attributes. This API is being deprecated soon.

query Parameters
all
required
string
Example: all=true

Get all plugin attributes.

subsystem
string
Default: "http"
Enum: "http" "stream"
Example: subsystem=stream

Get HTTP or Stream plugin attributes.

Responses

Response samples

Content type
application/json
{
  • "limit-conn": {
    },
  • "syslog": {
    },
  • "ip-restriction": {
    },
  • "mqtt-proxy": {
    }
}

Reload All Plugins

Hot reload all plugins for changes to the plugin source files to take effect.

Responses

Response samples

Content type
application/json
"done"

Plugin Config

Plugin config is used to configure plugin configurations that can be shared among other objects, such as routes.

See Plugin Configs for more information.

Get All Plugin Configs

Get all configured plugin configs.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create Plugin Config by ID

Create a plugin config with a custom ID.

path Parameters
id
required
integer
Example: 1

Specified plugin config ID.

Request Body schema: application/json
plugins
required
object
desc
string <= 256 characters
labels
object

Key-value pairs to specify attributes.

required
string or integer

Responses

Request samples

Content type
application/json
{
  • "desc": "desc",
  • "plugins": {
    }
}

Response samples

Content type
application/json
{
  • "key": "/apisix/plugin_configs/1",
  • "value": {
    }
}

Get Plugin Config by ID

Get a plugin config by ID.

path Parameters
id
required
string

Specified plugin config ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/plugin_configs/1",
  • "modifiedIndex": 151,
  • "createdIndex": 150
}

Update Plugin Config

Update a plugin config.

path Parameters
id
required
string

Specified plugin config ID.

Request Body schema: application/json
plugins
required
object
desc
string <= 256 characters
labels
object

Key-value pairs to specify attributes.

required
string or integer

Responses

Request samples

Content type
application/json
{
  • "plugins": {
    }
}

Response samples

Content type
application/json
{
  • "key": "/apisix/plugin_configs/1",
  • "value": {
    }
}

Delete Plugin Config by ID

Delete a plugin config by ID.

path Parameters
id
required
string

Specified plugin config ID.

query Parameters
force
string
Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

Content type
application/json
{
  • "key": "/apisix/plugin_configs/1",
  • "deleted": "1"
}

Plugin Metadata

Plugin metadata is used to configure the common metadata field(s) of all plugin instances sharing the same plugin name.

See Plugin Metadata for more information.

Get All Plugin Metadata

Get all plugin metadata.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create Plugin Metadata by Name

Create a plugin metadata by plugin name.

path Parameters
plugin_name
required
string

The specified plugin name

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "log_format": {
    }
}

Response samples

Content type
application/json
{
  • "key": "/apisix/plugin_metadata/syslog",
  • "value": {
    }
}

Get Plugin Metadata by Name

Get plugin metadata by plugin name.

path Parameters
plugin_name
required
string

The specified plugin name

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/plugin_metadata/syslog",
  • "modifiedIndex": 156,
  • "createdIndex": 156
}

Delete Plugin Metadata by Name

Delete a plugin metadata by plugin name.

path Parameters
plugin_name
required
string

The specified plugin name

query Parameters
force
string
Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

Content type
application/json
{
  • "key": "/apisix/plugin_metadata/syslog",
  • "deleted": "1"
}

Global Rule

A plugin global rule is used to create plugins that are triggered on every incoming request and executed before other plugins locally bound to objects, such as routes, services, consumers, consumer groups, or plugin configs.

See Global Rules for more information.

Get All Global Rules

Get all configured plugin global rules.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create Global Rule by ID

Create a plugin global rule with a custom ID.

path Parameters
id
required
string

Specified global rule ID.

Request Body schema: application/json
required
string or integer
plugins
required
object

Responses

Request samples

Content type
application/json
{
  • "plugins": {
    }
}

Response samples

Content type
application/json
{
  • "key": "/apisix/global_rules/1",
  • "value": {
    }
}

Get Global Rule by ID

Get a global rule by ID.

path Parameters
id
required
string

Specified global rule ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/global_rules/1",
  • "modifiedIndex": 137,
  • "createdIndex": 137
}

Update Global Rule

Update a plugin global rule.

path Parameters
id
required
string

Specified global rule ID.

Request Body schema: application/json
string or integer
plugins
required
object

Responses

Request samples

Content type
application/json
{
  • "plugins": {
    }
}

Response samples

Content type
application/json
{
  • "key": "/apisix/global_rules/1",
  • "value": {
    }
}

Delete Global Rule by ID

Delete a plugin global rule by ID.

path Parameters
id
required
string

Specified global rule ID.

query Parameters
force
string
Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

Content type
application/json
{
  • "key": "/apisix/global_rules/1",
  • "deleted": "1"
}

Stream Route

A stream route defines a path to one or more upstream services when APISIX functions as a stream proxy that operates on the transport layer for TCP and UDP connections.

See Stream Routes for more information.

Get All Stream Routes

Get all configured stream routes.

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "list": [
    ]
}

Create Stream Route

Create a stream route with an ID generated.

Request Body schema: application/json
desc
string <= 256 characters
string or integer
string or integer
sni
string
string or integer
IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string)

client IP

object
IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string)

server IP

object or object
plugins
object
server_port
integer

server port

Responses

Request samples

Content type
application/json
{
  • "server_addr": "127.0.0.1",
  • "server_port": 2000,
  • "upstream": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/stream_routes/00000000000000000176"
}

Get Stream Route by ID

Get stream route by ID.

path Parameters
id
required
string

Specified stream route ID.

Responses

Response samples

Content type
application/json
{
  • "id": "1",
  • "create_time": 1684392990,
  • "server_addr": "127.0.0.1",
  • "upstream": {
    },
  • "update_time": 1684392990,
  • "server_port": 2000
}

Create Stream Route by ID

Create a stream route with a specified ID.

path Parameters
id
required
string

Specified stream route ID.

Request Body schema: application/json
string or integer
desc
string <= 256 characters
string or integer
string or integer
sni
string
IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string)

client IP

object
IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string)

server IP

object or object
plugins
object
server_port
integer

server port

Responses

Request samples

Content type
application/json
{
  • "server_addr": "127.0.0.1",
  • "server_port": 2000,
  • "upstream": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/stream_routes/00000000000000000176"
}

Delete Stream Route by ID

Delete a stream route by ID.

path Parameters
id
required
string

The stream route id

query Parameters
force
string
Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

Content type
application/json
{
  • "deleted": "1",
  • "key": "/apisix/stream_routes/1"
}

SSL

An SSL certificate in Admin API is required to configure TLS or mTLS with client applications and configure mTLS with upstream services.

See SSL for more information.

Get All SSL

Get all configured SSL.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create SSL

Create an SSL with an ID generated.

Request Body schema: application/json
One of
One of
labels
object

Key-value pairs to specify attributes.

status
integer
Default: 1
Enum: 1 0

SSL status. 1: enable. 0: disable.

keys
Array of strings[ items [ 128 .. 65536 ] characters ]
key
required
string [ 128 .. 65536 ] characters
sni
required
string
string or integer
object
certs
Array of strings[ items [ 128 .. 65536 ] characters ]
type
string
Default: "server"
Enum: "server" "client"

APISIX acts as an SSL server or client.

cert
required
string [ 128 .. 65536 ] characters
snis
Array of strings non-empty

Responses

Request samples

Content type
application/json
{
  • "type": "server",
  • "sni": "test.com",
  • "cert": "<content of server.crt>",
  • "key": "<content of server.key>"
}

Response samples

Content type
application/json
{
  • "key": "/apisix/ssls/00000000000000000134",
  • "value": {
    }
}

Create an SSL by ID

Create an SSL with a custom ID.

path Parameters
id
required
string

Specified SSL ID.

Request Body schema: application/json
One of
One of
labels
object

Key-value pairs to specify attributes.

status
integer
Default: 1
Enum: 1 0

SSL status. 1: enable. 0: disable.

keys
Array of strings[ items [ 128 .. 65536 ] characters ]
key
required
string [ 128 .. 65536 ] characters
sni
required
string
ssl_protocols
Array of strings
Items Enum: "TLSv1.2" "TLSv1.3"
string or integer
object
certs
Array of strings[ items [ 128 .. 65536 ] characters ]
type
string
Default: "server"
Enum: "server" "client"

APISIX acts as an SSL server or client.

cert
required
string [ 128 .. 65536 ] characters
snis
Array of strings non-empty

Responses

Request samples

Content type
application/json
{
  • "type": "server",
  • "snis": [
    ],
  • "cert": "<content of server.crt>",
  • "key": "<content of key.crt>"
}

Response samples

Content type
application/json
{
  • "key": "/apisix/ssls/1",
  • "value": {
    }
}

Get SSL by ID

Get an SSL by ID.

path Parameters
id
required
string

Specified SSL ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/ssls/1",
  • "modifiedIndex": 133,
  • "createdIndex": 133
}

Delete SSL by ID

Delete an SSL by ID.

path Parameters
id
required
string

Specified SSL ID.

query Parameters
force
string
Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

Content type
application/json
{
  • "key": "/apisix/ssls/00000000000000000134",
  • "deleted": "1"
}

Secret

Secret is used to set up integration with an external secret manager, so that APISIX can establish connections and fetch secrets from the secret manager dynamically at runtime.

See Secrets for more information.

Get All Secrets

Get all configured secrets.

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "list": [
    ]
}

Get Secrets by ID

Get a secret by ID.

path Parameters
secretmanager
required
string

Any secret manager supported, e.g. vault.

id
required
string

The specified secrets ID.

Responses

Response samples

Content type
application/json
{
  • "createdIndex": 179,
  • "key": "/apisix/secrets/vault/1",
  • "value": {
    },
  • "modifiedIndex": 179
}

Create Secrets Configuration

Create a secrete configuration with a custom ID.

path Parameters
secretmanager
required
string

Any secret manager supported, e.g. vault.

id
required
string

The specified secrets ID.

Request Body schema: application/json
uri
required
string
prefix
required
string
token
required
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/secrets/vault/1"
}

Update Secrets

Update a secret configuration.

path Parameters
secretmanager
required
string

Any secret manager supported, e.g. vault.

id
required
string

The specified secrets ID.

Request Body schema: application/json
uri
required
string
prefix
required
string
token
required
string

Responses

Request samples

Content type
application/json
{
  • "token": "apisix"
}

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/secrets/vault/1"
}

Delete Secret by ID

Delete a secret by ID.

path Parameters
secretmanager
required
string

Any secret manager supported, e.g. vault.

id
required
string

The secrets id

query Parameters
force
string
Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

Content type
application/json
{
  • "deleted": "1",
  • "key": "/apisix/secrets/vault/1"
}

Proto

Proto is used to store protocol buffer (protobuf) definitions which define the service interface and message types used in communication with upstream gRPC services.

See Protos for more information.

Create Proto by ID

Create a proto with a custom ID.

path Parameters
id
required
string

Specified proto ID.

Request Body schema: application/json
content
required
string

Responses

Request samples

Content type
application/json
"{\n \"content\": \"syntax = \\\"proto3\\\";\n package helloworld;\n service Greeter {\n rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n }\n message HelloRequest {\n string name = 1;\n repeated string items = 2;\n }\n message HelloReply {\n string message = 1;\n repeated string items = 2;\n }\n message ErrorDetail {\n int64 code = 1;\n string message = 2;\n string type = 3;\n }\"\n}"

Response samples

Content type
application/json
{
  • "key": "/apisix/protos/1",
  • "value": {
    }
}

Get Proto by ID

Get a proto configuration by ID.

path Parameters
id
required
string

Specified proto ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "key": "/apisix/protos/1",
  • "modifiedIndex": 292,
  • "createdIndex": 292
}

Delete Proto by ID

Delete a proto by ID.

path Parameters
id
required
string

Specified proto ID.

query Parameters
force
string
Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

Content type
application/json
{
  • "key": "/apisix/protos/1",
  • "deleted": "1"
}

Get All Protos

Get all configured protos.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create Proto

Create a proto with an ID generated.

Request Body schema: application/json
content
required
string

Responses

Request samples

Content type
application/json
"{\n \"content\": \"syntax = \\\"proto3\\\";\n package helloworld;\n service Greeter {\n rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n }\n message HelloRequest {\n string name = 1;\n repeated string items = 2;\n }\n message HelloReply {\n string message = 1;\n repeated string items = 2;\n }\n message ErrorDetail {\n int64 code = 1;\n string message = 2;\n string type = 3;\n }\"\n}"

Response samples

Content type
application/json
{
  • "key": "/apisix/protos/00000000000000000293",
  • "value": {
    }
}

Schema Validation

Validate if the schema of a configuration is correct without sending a request to the Admin API for resource creation. This API can be used with all Admin API resources.

Validate Configuration Schema

Validate configuration schema without resource creation.

path Parameters
resource
required
string
Enum: "routes" "services" "upstreams" "consumers" "consumer_groups" "ssls" "gloabl_rules" "plugins" "plugin_metadata" "plugin_configs" "stream_routes" "secrets" "protos"
Example: routes

Type of resource.

Request Body schema: application/json
any

Responses

Request samples

Content type
application/json
{
  • "uri": 1980,
  • "upstream": {
    }
}

API7.ai Logo

API Management for Modern Architectures with Edge, API Gateway, Kubernetes, and Service Mesh.

Product

API7 Cloud

SOC2 Type IRed Herring

Copyright © APISEVEN Ltd. 2019 – 2024. Apache, Apache APISIX, APISIX, and associated open source project names are trademarks of the

Apache Software Foundation