diff --git a/app/_data/docs_nav_0.4.x.yml b/app/_data/docs_nav_0.4.x.yml index 1309a5dac630..6fa5222a3e8e 100644 --- a/app/_data/docs_nav_0.4.x.yml +++ b/app/_data/docs_nav_0.4.x.yml @@ -94,30 +94,29 @@ url: /admin-api/#plugin-object items: - - text: Retrieve Installed Plugins - url: /admin-api/#retrieve-installed-plugins + text: Add Plugin + url: /admin-api/#add-plugin - - text: Retrieve Plugin Schema - url: /admin-api/#retrieve-plugin-schema - - - text: Plugin Configuration Object routes - url: /admin-api/#plugin-configuration-object - items: + text: List all Plugins + url: /admin-api/#list-all-plugins - - text: Create Plugin Configuration - url: /admin-api/#create-plugin-configuration + text: List Plugins per API + url: /admin-api/#list-plugins-per-api - - text: List per-API Plugin Configurations - url: /admin-api/#list-per-api-plugin-configurations + text: Retrieve Plugin + url: /admin-api/#retrieve-plugin - - text: List all Plugin Configurations - url: /admin-api/#list-all-plugin-configurations + text: Update Plugin + url: /admin-api/#update-plugin - - text: Update Plugin Configuration - url: /admin-api/#update-plugin-configuration + text: Update or Add Plugin + url: /admin-api/#update-or-add-plugin - - text: Update or create Plugin Configuration - url: /admin-api/#update-or-create-plugin-configuration + text: Delete Plugin + url: /admin-api/#delete-plugin - - text: Delete Plugin Configuration - url: /admin-api/#delete-plugin-configuration + text: Retrieve Enabled Plugins + url: /admin-api/#retrieve-enabled-plugins + - + text: Retrieve Plugin Schema + url: /admin-api/#retrieve-plugin-schema diff --git a/app/docs/0.4.x/admin-api.md b/app/docs/0.4.x/admin-api.md index 31612f4bb2ab..b18a2b0830fd 100644 --- a/app/docs/0.4.x/admin-api.md +++ b/app/docs/0.4.x/admin-api.md @@ -4,12 +4,12 @@ title: Admin API api_body: | Attribute | Description ---:| --- - `name`
*optional* | The API name. If none is specified, will default to the `public_dns`. - `public_dns`
*semi-optional* | The public DNS address that points to your API. For example, `mockbin.com`. At least `public_dns` or `path` or both should be specified. - `path`
*semi-optional* | The public path that points to your API. For example, `/someservice`. At least `public_dns` or `path` or both should be specified. - `strip_path`
*optional* | Strip the `path` value before proxying the request to the final API. For example a request made to `/someservice/hello` will be resolved to `target_url/hello`. By default is `false`. - `preserve_host`
*optional* | Preserves the original `Host` header sent by the client, instead of replacing it with the hostname of the `target_url`. By default is `false`. - `target_url` | The base target URL that points to your API server, this URL will be used for proxying requests. For example, `https://mockbin.com`. + `name`
*optional* | The API name. If none is specified, will default to the `inbound_dns`. + `inbound_dns`
*semi-optional* | The public DNS address that points to your API. For example, `mockbin.com`. At least `inbound_dns` or `path` or both should be specified. + `path`
*semi-optional* | The public path that points to your API. For example, `/someservice`. At least `inbound_dns` or `path` or both should be specified. + `strip_path`
*optional* | Strip the `path` value before proxying the request to the final API. For example a request made to `/someservice/hello` will be resolved to `upstream_url/hello`. By default is `false`. + `preserve_host`
*optional* | Preserves the original `Host` header sent by the client, instead of replacing it with the hostname of the `upstream_url`. By default is `false`. + `upstream_url` | The base target URL that points to your API server, this URL will be used for proxying requests. For example, `https://mockbin.com`. consumer_body: | Attributes | Description @@ -22,7 +22,7 @@ plugin_configuration_body: | ---:| --- `name` | The name of the Plugin that's going to be added. Currently the Plugin must be installed in every Kong instance separately. `consumer_id`
*optional* | The unique identifier of the consumer that overrides the existing settings for this specific consumer on incoming requests. - `value.{property}` | The configuration properties for the Plugin which can be found on the plugins documentation page in the [Plugin Gallery](/plugins). + `config.{property}` | The configuration properties for the Plugin which can be found on the plugins documentation page in the [Plugin Gallery](/plugins). --- # Kong Admin API @@ -40,7 +40,7 @@ The Admin API accepts 2 content types on every endpoint: Simple enough for basic request bodies, you will probably use it most of the time. Note that when sending nested values, Kong expects nested objects to be referenced with dotted keys. Example: ``` -value.limit=10&value.period=seconds +config.limit=10&config.period=seconds ``` - **application/json** @@ -49,7 +49,7 @@ Handy for complex bodies (ex: complex plugin configuration), in that case simply ```json { - "value": { + "config": { "limit": 10, "period": "seconds" } @@ -149,11 +149,11 @@ The API object describes an API that's being exposed by Kong. In order to do tha ```json { "name": "Mockbin", - "public_dns": "mockbin.com", + "inbound_dns": "mockbin.com", "path": "/someservice", "strip_path": false, "preserve_host": false, - "target_url": "https://mockbin.com" + "upstream_url": "https://mockbin.com" } ``` @@ -179,8 +179,8 @@ HTTP 201 Created { "id": "4d924084-1adb-40a5-c042-63b19db421d1", "name": "Mockbin", - "public_dns": "mockbin.com", - "target_url": "http://mockbin.com", + "inbound_dns": "mockbin.com", + "upstream_url": "http://mockbin.com", "preserve_host": false, "created_at": 1422386534 } @@ -208,8 +208,8 @@ HTTP 200 OK { "id": "4d924084-1adb-40a5-c042-63b19db421d1", "name": "Mockbin", - "public_dns": "mockbin.com", - "target_url": "https://mockbin.com", + "inbound_dns": "mockbin.com", + "upstream_url": "https://mockbin.com", "preserve_host": false, "created_at": 1422386534 } @@ -229,8 +229,8 @@ Attributes | Description ---:| --- `id`
*optional* | A filter on the list based on the apis `id` field. `name`
*optional* | A filter on the list based on the apis `name` field. -`public_dns`
*optional* | A filter on the list based on the apis `public_dns` field. -`target_url`
*optional* | A filter on the list based on the apis `target_url` field. +`inbound_dns`
*optional* | A filter on the list based on the apis `inbound_dns` field. +`upstream_url`
*optional* | A filter on the list based on the apis `upstream_url` field. `size`
*optional, default is __100__* | A limit on the number of objects to be returned. `offset`
*optional* | A cursor used for pagination. `offset` is an object identifier that defines a place in the list. @@ -247,16 +247,16 @@ HTTP 200 OK { "id": "4d924084-1adb-40a5-c042-63b19db421d1", "name": "Mockbin", - "public_dns": "mockbin.com", - "target_url": "https://mockbin.com", + "inbound_dns": "mockbin.com", + "upstream_url": "https://mockbin.com", "preserve_host": false, "created_at": 1422386534 }, { "id": "3f924084-1adb-40a5-c042-63b19db421a2", "name": "PrivateAPI", - "public_dns": "internal.api.com", - "target_url": "http://private.api.com", + "inbound_dns": "internal.api.com", + "upstream_url": "http://private.api.com", "preserve_host": false, "created_at": 1422386585 } @@ -291,8 +291,8 @@ HTTP 200 OK { "id": "4d924084-1adb-40a5-c042-63b19db421d1", "name": "Mockbin2", - "public_dns": "mockbin.com", - "target_url": "http://mockbin.com", + "inbound_dns": "mockbin.com", + "upstream_url": "http://mockbin.com", "preserve_host": false, "created_at": 1422386534 } @@ -519,82 +519,9 @@ HTTP 204 NO CONTENT ## Plugin Object -Retrieve the installed plugins on your node and their configuration schema. +A Plugin entity represents a plugin configuration that will be executed during the HTTP request/response workflow, and it's how you can add functionalities to APIs that run behind Kong, like Authentication or Rate Limiting for example. You can find more information about how to install and what values each plugin takes by visiting the [Plugin Gallery](/plugins). -**Reminder:** Installed plugins does not mean a plugin is enabled. To enabled a plugin, you have to configure it for a given API. See [Plugin Configuration Object](#plugin-configuration-object). - ---- - -### Retrieve Installed Plugins - -Retrieve a list of all installed plugins on the Kong node. - -#### Endpoint - -
/plugins/
- -#### Response - -``` -HTTP 200 OK -``` - -```json -{ - "enabled_plugins": [ - "ssl", - "key-auth", - "basic-auth", - "oauth2", - "rate-limiting", - "tcp-log", - "udp-log", - "file-log", - "http-log", - "cors", - "request-transformer", - "response-transformer", - "request-size-limiting", - "mashape-analytics" - ] -} -``` - -### Retrieve Plugin Schema - -Retrieve the schema of a plugin's configuration. This is useful to understand what fields a plugin accepts, and can be used for building third-party integrations to the Kong's plugin system. - -
/plugins/{plugin name}/schema
- -#### Response - -``` -HTTP 200 OK -``` - -```json -{ - "fields": { - "hide_credentials": { - "default": false, - "type": "boolean" - }, - "key_names": { - "default": "function", - "required": true, - "type": "array" - } - } -} -``` - ---- - -## Plugin Configuration Object - -The Plugin Configuration object represents a plugin configuration that will be executed during the HTTP request/response workflow, and it's how you can add functionalities to APIs that run behind Kong, like Authentication or Rate Limiting for example. You can find more information about how to install and what values each plugin takes by visiting the [Plugin Gallery](/plugins). - -When creating a Plugin Configuration on top of an API, every request made by a client will be evaluated by the plugin configuration you setup. Sometimes the Plugin Configuration needs to be tuned to different values for some specific consumers, you can do that by specifying the `consumer_id` value. +When creating adding Plugin on top of an API, every request made by a client will be evaluated by the Plugin's configuration you setup. Sometimes the Plugin needs to be tuned to different values for some specific consumers, you can do that by specifying the `consumer_id` value. ```json { @@ -602,7 +529,7 @@ When creating a Plugin Configuration on top of an API, every request made by a c "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4", "name": "rate-limiting", - "value": { + "config": { "minute": 20, "hour": 500 }, @@ -613,7 +540,7 @@ When creating a Plugin Configuration on top of an API, every request made by a c --- -### Create Plugin Configuration +### Add Plugin #### Endpoint @@ -639,7 +566,7 @@ HTTP 201 Created "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4", "name": "rate-limiting", - "value": { + "config": { "minute": 20, "hour": 500 }, @@ -650,11 +577,11 @@ HTTP 201 Created --- -### List Per-API Plugin Configurations +### List All Plugins #### Endpoint -
/apis/{api name or id}/plugins/
+
/plugins/
#### Request Querystring Parameters @@ -681,7 +608,7 @@ HTTP 200 OK "id": "4d924084-1adb-40a5-c042-63b19db421d1", "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", "name": "rate-limiting", - "value": { + "config": { "minute": 20, "hour": 500 }, @@ -693,7 +620,7 @@ HTTP 200 OK "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4", "name": "rate-limiting", - "value": { + "config": { "minute": 300, "hour": 20000 }, @@ -701,19 +628,17 @@ HTTP 200 OK "created_at": 1422386585 } ], - "next": "http://localhost:8001/plugins_configurations/?size=10&offset=4d924084-1adb-40a5-c042-63b19db421d1" + "next": "http://localhost:8001/plugins?size=10&offset=4d924084-1adb-40a5-c042-63b19db421d1" } ``` --- -### List All Plugin Configurations - -You can use the `/plugins_configuration` endpoint to acces a global list of all the configured plugins on your cluster. +### List Plugins per API #### Endpoint -
/plugins_configurations/
+
/apis/{api name or id}/plugins/
#### Request Querystring Parameters @@ -740,7 +665,7 @@ HTTP 200 OK "id": "4d924084-1adb-40a5-c042-63b19db421d1", "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", "name": "rate-limiting", - "value": { + "config": { "minute": 20, "hour": 500 }, @@ -752,7 +677,7 @@ HTTP 200 OK "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4", "name": "rate-limiting", - "value": { + "config": { "minute": 300, "hour": 20000 }, @@ -760,13 +685,48 @@ HTTP 200 OK "created_at": 1422386585 } ], - "next": "http://localhost:8001/plugins_configurations/?size=10&offset=4d924084-1adb-40a5-c042-63b19db421d1" + "next": "http://localhost:8001/plugins?size=10&offset=4d924084-1adb-40a5-c042-63b19db421d1" +} +``` + +--- + +## Retrieve Plugin + +
/plugins/{id}
+ +Attributes | Description +---:| --- +`id`
**required** | The unique identifier of the plugin configuration to update on this API + +#### Request Body + +{{ page.plugin_configuration_body }} + +#### Response + +``` +HTTP 200 OK +``` + +```json +{ + "id": "4d924084-1adb-40a5-c042-63b19db421d1", + "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", + "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4", + "name": "rate-limiting", + "config": { + "minute": 20, + "hour": 500 + }, + "enabled": true, + "created_at": 1422386534 } ``` --- -### Update Plugin Configuration +### Update Plugin #### Endpoint @@ -793,7 +753,7 @@ HTTP 200 OK "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4", "name": "rate-limiting", - "value": { + "config": { "minute": 20, "hour": 500 }, @@ -804,7 +764,7 @@ HTTP 200 OK --- -### Update Or Create Plugin Configuration +### Update or Add Plugin #### Endpoint @@ -830,7 +790,7 @@ See POST and PATCH responses. --- -### Delete Plugin Configuration +### Delete Plugin #### Endpoint @@ -846,3 +806,70 @@ Attributes | Description ``` HTTP 204 NO CONTENT ``` + +--- + +### Retrieve Enabled Plugins + +Retrieve a list of all installed plugins on the Kong node. + +#### Endpoint + +
/plugins/enabled
+ +#### Response + +``` +HTTP 200 OK +``` + +```json +{ + "enabled_plugins": [ + "ssl", + "keyauth", + "basicauth", + "oauth2", + "ratelimiting", + "tcplog", + "udplog", + "filelog", + "httplog", + "cors", + "request_transformer", + "response_transformer", + "requestsizelimiting", + "analytics" + ] +} +``` + +--- + +### Retrieve Plugin Schema + +Retrieve the schema of a plugin's configuration. This is useful to understand what fields a plugin accepts, and can be used for building third-party integrations to the Kong's plugin system. + +
/plugins/schema/{plugin name}
+ +#### Response + +``` +HTTP 200 OK +``` + +```json +{ + "fields": { + "hide_credentials": { + "default": false, + "type": "boolean" + }, + "key_names": { + "default": "function", + "required": true, + "type": "array" + } + } +} +``` diff --git a/app/docs/0.4.x/configuration.md b/app/docs/0.4.x/configuration.md index 793b27b48776..cad9e57bd847 100644 --- a/app/docs/0.4.x/configuration.md +++ b/app/docs/0.4.x/configuration.md @@ -157,7 +157,7 @@ Currently, Kong only supports [Cassandra v{{site.data.kong_latest.dependencies.c databases_available: cassandra: properties: - hosts: + contact_points: - "localhost:9042" timeout: 1000 keyspace: kong @@ -168,15 +168,15 @@ databases_available: A dictionary of properties needed for Kong to connect to a given database (where `.*` is the name of the database). - **`databases_available.*.properties.hosts`** + **`databases_available.*.properties.contact_points`** - The hosts(s) on which Kong should connect to for accessing your Cassandra cluster. Can either be a string or a list of strings containing the host and the port of your node(s). + The contact points on which Kong should connect to for accessing your Cassandra cluster. Can either be a string or a list of strings containing the host and the port of your node(s). **Example:** ```yaml properties: - hosts: + contact_points: - "52.5.149.55" # will connect on port 9042 (default) - "52.5.149.56:9000" # will connect on port 9000 ``` diff --git a/app/docs/0.4.x/getting-started/adding-your-api.md b/app/docs/0.4.x/getting-started/adding-your-api.md index 729b31fe6e87..253de49eb85c 100644 --- a/app/docs/0.4.x/getting-started/adding-your-api.md +++ b/app/docs/0.4.x/getting-started/adding-your-api.md @@ -22,8 +22,8 @@ In this section, you'll be adding your API to the Kong layer. This is the first $ curl -i -X POST \ --url http://localhost:8001/apis/ \ --data 'name=mockbin' \ - --data 'target_url=http://mockbin.com/' \ - --data 'public_dns=mockbin.com' + --data 'upstream_url=http://mockbin.com/' \ + --data 'inbound_dns=mockbin.com' ``` **Note:** Kong handles API configuration requests on port `:8001` @@ -45,8 +45,8 @@ In this section, you'll be adding your API to the Kong layer. This is the first Server: kong/0.1.1beta-2 { - "public_dns": "mockbin.com", - "target_url": "http://mockbin.com/", + "inbound_dns": "mockbin.com", + "upstream_url": "http://mockbin.com/", "id": "2eec1cb2-7093-411a-c14e-42e67142d2c4", "created_at": 1428456369000, "name": "mockbin" @@ -65,10 +65,10 @@ In this section, you'll be adding your API to the Kong layer. This is the first --header 'Host: mockbin.com' ``` - A successful response means Kong is now forwarding requests to the `target_url` we passed in the first step and giving us the response back. Kong knows to do this through the header defined in the above cURL request: + A successful response means Kong is now forwarding requests to the `upstream_url` we passed in the first step and giving us the response back. Kong knows to do this through the header defined in the above cURL request: **Note:** Kong handles proxy requests on port `:8000` diff --git a/app/docs/0.4.x/getting-started/enabling-plugins.md b/app/docs/0.4.x/getting-started/enabling-plugins.md index 9bd2dc63cb1c..cfcb57389efc 100644 --- a/app/docs/0.4.x/getting-started/enabling-plugins.md +++ b/app/docs/0.4.x/getting-started/enabling-plugins.md @@ -48,7 +48,7 @@ First, we'll have you configure and enable the [key-auth][key-auth] plugin to ad --data 'name=key-auth' ``` - **Note:** This plugin also accepts a `value.key_names` parameter, which defaults to `[apikey]`. It is a list of headers and parameters names (both are supported) that are supposed to contain the API key during a request. + **Note:** This plugin also accepts a `config.key_names` parameter, which defaults to `[apikey]`. It is a list of headers and parameters names (both are supported) that are supposed to contain the API key during a request. 4. ### Verify that the plugin is enabled for your API diff --git a/app/docs/0.4.x/proxy.md b/app/docs/0.4.x/proxy.md index a36fc5eaf758..97794a86747a 100644 --- a/app/docs/0.4.x/proxy.md +++ b/app/docs/0.4.x/proxy.md @@ -65,12 +65,12 @@ As explained in the [Adding your API][adding-your-api] quickstart guide, Kong is $ curl -i -X POST \ --url http://localhost:8001/apis/ \ -d 'name=mockbin' \ - -d 'target_url=http://mockbin.com/' \ - -d 'public_dns=mockbin.com' \ + -d 'upstream_url=http://mockbin.com/' \ + -d 'inbound_dns=mockbin.com' \ -d 'path=/status' ``` -This request tells Kong to add an API named "**mockbin**", with its upstream resource being located at "**http://mockbin.com**". The `public_dns` and `path` properties are the ones used by Kong to route a request to that API. Both properties are not required but at least one must be specified. +This request tells Kong to add an API named "**mockbin**", with its upstream resource being located at "**http://mockbin.com**". The `inbound_dns` and `path` properties are the ones used by Kong to route a request to that API. Both properties are not required but at least one must be specified. Once this request is processed by Kong, the API is stored in your Cassandra cluster and a request to the **Proxy port** will trigger a query to Cassandra and put your API in Kong's proxying cache. @@ -80,7 +80,7 @@ Once this request is processed by Kong, the API is stored in your Cassandra clus #### Using the "**Host**" header -Now that we added an API to Kong (via the Admin API), Kong can proxy it via the `8000` port. One way to do so is to specify the API's `public_dns` value in the `Host` header of your request: +Now that we added an API to Kong (via the Admin API), Kong can proxy it via the `8000` port. One way to do so is to specify the API's `inbound_dns` value in the `Host` header of your request: ```bash $ curl -i -X GET \ @@ -88,7 +88,7 @@ $ curl -i -X GET \ --header 'Host: mockbin.com' ``` -By doing so, Kong recognizes the `Host` value as being the `public_dns` of the "mockbin" API. The request will be routed to the upstream API and Kong will execute any configured [plugin][plugins] for that API. +By doing so, Kong recognizes the `Host` value as being the `inbound_dns` of the "mockbin" API. The request will be routed to the upstream API and Kong will execute any configured [plugin][plugins] for that API.
Going to production: If you're planning to go into production with your setup, you'll most likely not want your consumers to manually set the "Host" header on each request. You can let Kong and DNS take care of it by simply setting an A or CNAME record on your domain pointing to your Kong installation. Hence, any request made to `example.org` will already contain a `Host: example.org` header. @@ -108,11 +108,11 @@ This request will be proxied just as well by Kong. #### Using a wildcard DNS -Sometimes you might want to route all requests matching a wildcard DNS to your upstream services. A "**public_dns**" wildcard name may contain an asterisk only on the name’s start or end, and only on a dot border. +Sometimes you might want to route all requests matching a wildcard DNS to your upstream services. An "**inbound_dns**" wildcard name may contain an asterisk only on the name’s start or end, and only on a dot border. -A "**public_dns**" of form `*.example.org` will route requests with "**Host**" values such as `a.example.org` or `x.y.example.org`. +An "**inbound_dns**" of form `*.example.org` will route requests with "**Host**" values such as `a.example.org` or `x.y.example.org`. -A "**public_dns**" of form `example.*` will route requests with "**Host**" values such as `example.com` or `example.org`. +An "**inbound_dns**" of form `example.*` will route requests with "**Host**" values such as `example.com` or `example.org`. --- @@ -127,7 +127,7 @@ $ curl -i -X GET \ --url http://localhost:8000/status/200 ``` -You will notice this command makes a request to `KONG_URL:PROXY_PORT/status/200`. Since the configured `target_url` is `http://mockbin.com/`, the request will hit the upstream service at `http://mockbin.com/status/200`. +You will notice this command makes a request to `KONG_URL:PROXY_PORT/status/200`. Since the configured `upstream_url` is `http://mockbin.com/`, the request will hit the upstream service at `http://mockbin.com/status/200`. #### Using the "**strip_path**" property