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.

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:

  1. curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r1' \
  2.     -H 'X-API-KEY: <api-key>' \
  3.     -H 'Content-Type: application/json' \
  4.     -d '{
  5.     "uri": "/apisix/plugin/jwt/sign",
  6.     "plugins": {
  7.         "public-api": {}
  8.     }
  9. }'

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

  1. 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:

  1. curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r2' \
  2.     -H 'X-API-KEY: <api-key>' \
  3.     -H 'Content-Type: application/json' \
  4.     -d '{
  5.     "uri": "/gen_token",
  6.     "plugins": {
  7.         "public-api": {
  8.             "uri": "/apisix/plugin/jwt/sign"
  9.         }
  10.     }
  11. }'

Now you can make requests to this new endpoint:

  1. 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:

  1. curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r2' \
  2.     -H 'X-API-KEY: <api-key>' \
  3.     -H 'Content-Type: application/json' \
  4.     -d '{
  5.     "uri": "/gen_token",
  6.     "plugins": {
  7.         "public-api": {
  8.             "uri": "/apisix/plugin/jwt/sign"
  9.         },
  10.         "key-auth": {}
  11.     }
  12. }'

Now, only authenticated requests are allowed:

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

The below request will fail:

  1. curl -i 'http://127.0.0.1:9080/gen_token?key=user-key'
  1. 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.

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.   "uri": "/hello",
  4.   "upstream": {
  5.     "type": "roundrobin",
  6.     "nodes": {
  7.       "127.0.0.1:1980": 1
  8.     }
  9.   }
  10. }'