docs: add a 'Getting Started' section to README

[thibaultcha]

Add a "Getting Started" section to the README (could later be moved to getkong.org). It describes adding an API, querying it, adding a plugin (authentication), and re-querying the API.

Writing this raised some concerns:

• The API routes do not feel RESTful The API routing does not feel RESTful #98
• It feels weird to be able to create empty accounts Accounts creation on empty request #96
• headerauth and queryauth should probably be the same plugin [headerauth] [queryauth] #95
• it's a lot of stuff to configure...

@thefosk @montanaflynn @nijikokun @sinzone Feel free to comment or checkout and improve. Here is a copy-pasta:

Getting started

Kong will look by default for a configuration file at /etc/kong/kong.yml. Make sure to copy the provided kong.yml there and edit it to let Kong access your Cassandra cluster.

Let's start Kong:

$ kong start

This should have run the migrations to prepare your Cassandra keyspace, and you should see a success message if Kong has started.

Kong listens on these ports:

• :8000: requests proxying
• :8001: Kong's configuration API by which you can add APIs and accounts

Hello World: Proxying your first API

Let's add mockbin as an API:

$ curl -i -X POST \
  --url http://localhost:8001/apis/ \
  --data 'name=mockbin&target_url=http://mockbin.com/&public_dns=mockbin.com'
HTTP/1.1 201 Created
...

And query it through Kong:

$ curl -i -X GET \
  --url http://localhost:8000/ \
  --header 'Host: mockbin.com'
HTTP/1.1 200 OK
...

Accounts and plugins

One of Kong's core principle is its extensibility through plugins, which allow you to add features to your APIs.

Let's configure the headerauth plugin to add authentication to your API. Make sure it is in the plugins_available property of your configuration.

# Make sure the api_id parameter matches the one of mockbin created earlier
$ curl -i -X POST \
  --url http://localhost:8001/plugins/ \
  --data 'name=headerauth&api_id=<api_id>&value.header_names=apikey'
HTTP/1.1 201 Created
...

If we make the same request again:

$ curl -i -X GET \
  --url http://localhost:8000/ \
  --header 'Host: mockbin.com'
HTTP/1.1 403 Forbidden
...
{"message":"Your authentication credentials are invalid"}

To authenticate against your API, you now need to create an account associated with an application. An application links an account and an API.

$ curl -i -X POST \ 
  --url http://localhost:8001/accounts/
  --data ''
HTTP/1.1 201 Created
...

# Make sure the given account_id matches the freshly created account
$ curl -i -X POST \
  --url http://localhost:8001/applications/
  --data 'public_key=123456&account_id=<account_id>'
HTTP/1.1 201 Created
...

That application (which has "123456" as an API key) can now consume authenticated APIs such as the previously configured mockbin:

$ curl -i -X GET \
  --url http://localhost:8000/ \
  --header 'Host: mockbin.com' \
  --header 'apikey: 123456'
HTTP/1.1 200 OK
...

To go further into mastering Kong, refer to the complete documentation.

[nijikokun]

First paragraphs need some rework, explain responses so people understand what api_id, and account_id is and how they obtain them.

1. What is headerauth plugin? How do I find information about it?
2. Where did api_id come from?
3. Where did account_id come from?
4. What is value.header_names for and why are you setting it to apikey
5. Is there a copy command for the kong.yml? Where is it normally located?
6. Why did I get that error message after adding that plugin? Was the plugin activated? On all nodes or one? Can I read more about it somewhere?
7. What am I querying on kong under proxy your api example? How does that work? Why are the ports different, good time to explain the difference of the ports again to really drive home the difference between the two.

[thibaultcha]

1. valid point
2. 3. I explained in the comments every time.
3. My philosophy was to not enter too deep into details here and rather link to "more docs" at the end of the tutorial. Also in the future this parameter should have a default
4. Depends on where luarocks is installed. More work needed to automatically put it to /etc/kong (Leverage luarocks if possible, or Makefile (breaks the "luarocks-only" install) or rely on OS package managers (thus would not work out of the box for luarocks installs again)
5. valid point
6. valid point

Thanks

[nijikokun]

1. 2 & 3 didn't read the comments, didn't jump out at me, easy to gloss over and miss a critical detail (light grey text on a grey background) showing response examples would be amazing here, so the user gets full reference, even without doing the commands.
2. 3 It would be best to link to the plugin page incase the user wants to know more, and brief introduction into what is going on.
3. 4 less of automatically, but more of here is a generic cp function replace this path with where it exists to place it under /etc/kong

[thibaultcha]

Note to self: example of what plugins_available should look like in the configuration.

[thibaultcha]

New version then, a little bit verbose:

diff between first proposed version and this one

Copy-paste:

Getting started

Kong will look by default for a configuration file at /etc/kong/kong.yml. If you installed Kong from luarocks, you can copy the default configuration from the luarocks tree (luarocks --help to print it). Usually:

cp /usr/local/lib/luarocks/rocks/kong/<kong_version>/conf/kong.yml /etc/kong/kong.yml

Edit the configuration to let Kong access your Cassandra cluster.

Let's start Kong:

$ kong start

This should have run the migrations to prepare your Cassandra keyspace, and you should see a success message if Kong has started.

Kong listens on these ports:

• :8000: requests proxying
• :8001: Kong's configuration API by which you can add APIs and accounts

Hello World: Proxying your first API

Let's add mockbin as an API:

$ curl -i -X POST \
  --url http://localhost:8001/apis/ \
  --data 'name=mockbin&target_url=http://mockbin.com/&public_dns=mockbin.com'
HTTP/1.1 201 Created

We used the 8001 port, the one of the configuration API.

And query it through Kong, by using the 8000 port, the one actually proxying requests:

$ curl -i -X GET \
  --url http://localhost:8000/ \
  --header 'Host: mockbin.com'
HTTP/1.1 200 OK

Kong just forwareded our request to target_url of mockbin and sent us the response.

Accounts and plugins

One of Kong's core principle is its extensibility through plugins, which allow you to add features to your APIs.

Let's configure the headerauth plugin to add authentication to your API.

1. Enable the plugin

Make sure it is in the plugins_available property of your node's configuration:

plugins_available:
  - headerauth

This will make Kong load the plugin. If the plugin was not previously marked as available, restart Kong:

$ kong restart

Repeat this step for every node in your cluster.

2. Configure the plugin for an API

To enable this plugin on an API, retrieve the API id (as the one of the freshly created mockbin API) and perform a POST request with the following parameters:

name: name of the plugin to create a configuration for.
api_id: id of the API this plugin will be added to.
value.header_names: value is a property of every plugin, representing their configuration. header_names will here be a list of headers in which users can pass their API key.

$ curl -i -X POST \
  --url http://localhost:8001/plugins/ \
  --data 'name=headerauth&api_id=<api_id>&value.header_names=apikey'
HTTP/1.1 201 Created
...
{
  "api_id": "<api_id>",
  "value": { "header_names":["apikey"], "hide_credentials":false },
  "id": "<id>",
  "enabled": true,
  "name": "headerauth"
}

Here, the plugin has been successfully created and enabled.

If you make the same request against the mockbin API again:

$ curl -i -X GET \
  --url http://localhost:8000/ \
  --header 'Host: mockbin.com'
HTTP/1.1 403 Forbidden
...
{ "message": "Your authentication credentials are invalid" }

This request did not provide a header named apikey (as specified by our plugin configuration) and is thus Forbidden. Kong does not proxy the request to the final API.

To authenticate against your API, you now need to create an account associated with an application. An application links an account and a plugin, this way, an account can consume different APIs with different applications (and different keys).

$ curl -i -X POST \ 
  --url http://localhost:8001/accounts/
  --data ''
HTTP/1.1 201 Created

# Make sure the given account_id matches the freshly created account
$ curl -i -X POST \
  --url http://localhost:8001/applications/
  --data 'public_key=123456&account_id=<account_id>'
HTTP/1.1 201 Created

That application (which has 123456 as an API key) can now consume APIs having an authentication requirement such as our example. If we make the same query again, but with an apikey header:

$ curl -i -X GET \
  --url http://localhost:8000/ \
  --header 'Host: mockbin.com' \
  --header 'apikey: 123456'
HTTP/1.1 200 OK

Your user can now consume this API.

To go further into mastering Kong and its plugins, refer to the complete documentation.

[thibaultcha]

The README could probably still contain the 1st part (adding an API and querying it) with a link to the website and the full Getting Started.

Again, feel free to improve.

[montanaflynn]

The section "Accounts and plugins" is the most complicated and confusing because it doesn't mention applications in the header and starts off with enabling a plugin. How APIs, accounts, applications and plugins interact with each other could be better explained in this section.

Actually I think it should be broken into three sections:

• Adding an account
• Adding an application
• Enabling headerauth plugin

[montanaflynn]

I find it weird that we have applications / accounts in the core if they are required for the auth plugins, maybe I'm not seeing the bigger picture use for them? Like will all plugins will have access to them and you can enable plugins on a per account or application basis?

[thibaultcha]

Adding an account
Adding an application
Enabling headerauth plugin

Yep, I was wondering wether or not I should use that order instead.

I find it weird that we have applications / accounts in the core if they are required for the auth plugins,

Valid point, to discuss in meeting