[feature] RESTful Admin API

[thibaultcha]

This is a refactor of the Admin API to allow for a more RESTful experience (#98) and an easier and more flexible way to create plugins that have API endpoints.

• The file structure changed.
• The tests changed and should be much stronger.
• The way of building endpoints too, taking advantages of Lapis' before and on_error callbacks.
• It is worth adding that since [feature] Admin API now supports form-encoded and json #236 all POST, PUT, PATCH endpoints support x-ww-application-form-encoded as well as application/json.
• ⚠️ It adds a migration to be able to select keyauth_credentials and basicauth_credentials by consumer_id.

Globally: less abstraction, less god-class pattern for more flexibility. Creating this kind of API is not that easy with Lapis but this is still a good shot I think, and can still be improved later.

New routes

This is a list of all the routes currently supported (trailing slash doesn't matter):

/
/apis/ (GET,POST,PUT)
/apis/:name_or_id (GET,PATCH,DELETE)
/apis/:name_or_id/plugins/ (GET,POST,PUT)
/apis/:name_or_id/plugins/:name_or_id (GET,PATCH,DELETE)
/consumers/ (same methods as above)
/consumers/:username_or_id
# the following are still supported but deprecated
/plugins_configurations/
/plugins_configurations/:id

And the current plugins with an API are moved to:

/consumers/:username_or_id/keyauth/
/consumers/:username_or_id/keyauth/:id
/consumers/:username_or_id/basicauth/
/consumers/:username_or_id/basicauth/:id

Changes to the documentation

The documentation should reflect the new routes changes, the content types support, and something very nice is now the ability to remove the "Retrieve the id of the created API/Consumer..." etc. Now we can simply pass the name of an API:

$ curl -i -X POST \
   --url http://localhost:8001/plugins_configurations/ \
   --data 'name=keyauth' \
   --data 'api_id=YOUR_API_ID' \
   --data 'value.key_names=apikey'

becomes:

curl -i -X POST \
   --url http://localhost:8001/mockbin/plugins/ \
   --data 'name=keyauth' \

(key_names is apikey by default since #253).

How to extend the API

If for the core, add a file in kong/plugins/api/routes. If for a plugin, it should be added in the plugin's directory, named api.lua.

Template:

local crud = require "kong.api.crud_helpers"

return {
  ["/consumers/"] = {
    GET = function(self, dao_factory)
      crud.paginated_set(self, dao_factory.consumers)
    end,

    PUT = function(self, dao_factory)
      crud.put(self.params, dao_factory.consumers)
    end,

    POST = function(self, dao_factory)
      crud.post(self.params, dao_factory.consumers)
    end
  },

  ["/consumers/:username_or_id"] = {
    before = function(self, dao_factory, helpers)
      crud.find_consumer_by_username_or_id(self, dao_factory, helpers)
    end,

    GET = function(self, dao_factory, helpers)
      return helpers.responses.send_HTTP_OK(self.consumer)
    end,

    PATCH = function(self, dao_factory, helpers)
      self.params.id = self.consumer.id
      crud.patch(self.params, dao_factory.consumers)
    end,

    DELETE = function(self, dao_factory, helpers)
      crud.delete(self.consumer.id, dao_factory.consumers)
    end
  }
}

You get one before and on_error function for each endpoint. on_error is implemented by default, allowing the developer to yield errors (especially DAO errors) like this:

-- DAO call
if err then
  helpers.yield_error(err) -- will send the proper status code and error message
end

A bonus are the crud_helpers, since otherwise a lot of code would be duplicated. They are just helpers that are not necessary, one could implement some endpoints without them, as they simply wrap calls to the DAO and the error handling.

---

Feedback/tests are welcomed before merging this, I will maybe polish it but at least it's opening the discussion.

[coveralls]

Coverage decreased (-3.76%) to 65.52% when pulling 4605e51 on feature/restful-api into ec28b4e on master.

[thibaultcha]

Merging this since I got no review but it needs to be in the wild to be tested before releasing.