Skip to main content
Version: 3.0.0-beta

public-api

Description#

The public-api is used for exposing an API endpoint through a general HTTP API router.

When you are using custom Plugins, you can use the public-api Plugin to define a fixed, public API for a particular functionality. For example, you can create a public API endpoint /apisix/plugin/jwt/sign for JWT authentication using the jwt-auth Plugin.

note

The public API added in a custom Plugin is not exposed by default and the user should manually configure a Route and enable the public-api Plugin on it.

Attributes#

NameTypeRequiredDefaultDescription
uristringFalse""URI of the public API. When setting up a Route, use this attribute to configure the original public API URI.

Example usage#

The example below uses the jwt-auth Plugin and the key-auth Plugin along with the public-api Plugin. Refer to their documentation for it configuration. This step is omitted below and only explains the configuration of the public-api Plugin.

Basic usage#

You can enable the Plugin on a specific Route as shown below:

curl -X PUT 'http://127.0.0.1:9180/apisix/admin/routes/r1' \
-H 'X-API-KEY: <api-key>' \
-H 'Content-Type: application/json' \
-d '{
"uri": "/apisix/plugin/jwt/sign",
"plugins": {
"public-api": {}
}
}'

Now, if you make a request to the configured URI, you will receive a JWT response:

curl 'http://127.0.0.1:9080/apisix/plugin/jwt/sign?key=user-key'

Using custom URI#

You can also use a custom URI for exposing the API as shown below:

curl -X PUT 'http://127.0.0.1:9180/apisix/admin/routes/r2' \
-H 'X-API-KEY: <api-key>' \
-H 'Content-Type: application/json' \
-d '{
"uri": "/gen_token",
"plugins": {
"public-api": {
"uri": "/apisix/plugin/jwt/sign"
}
}
}'

Now you can make requests to this new endpoint:

curl 'http://127.0.0.1:9080/gen_token?key=user-key'

Securing the Route#

You can use the key-auth Plugin to add authentication and secure the Route:

curl -X PUT 'http://127.0.0.1:9180/apisix/admin/routes/r2' \
-H 'X-API-KEY: <api-key>' \
-H 'Content-Type: application/json' \
-d '{
"uri": "/gen_token",
"plugins": {
"public-api": {
"uri": "/apisix/plugin/jwt/sign"
},
"key-auth": {}
}
}'

Now, only authenticated requests are allowed:

curl -i 'http://127.0.0.1:9080/gen_token?key=user-key' \
-H "apikey: test-apikey"
HTTP/1.1 200 OK

The below request will fail:

curl -i 'http://127.0.0.1:9080/gen_token?key=user-key'
HTTP/1.1 401 Unauthorized

Disable Plugin#

To disable the public-api Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/hello",
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
}
}'