Update API Umbrella API docs to describe all methods and parameters

[brylie]

Document all Admin API endpoints, including parameters (required and optional), requests, and responses.

User Stories

As a developer
I need to understand the API Umbrella Admin API
so that I can develop custom software to integrate with API Umbrella features

As a project manager
I need to understand the API Umbrella Admin API
so that I can coordinate development efforts around API Umbrella features

Tasks

Document the following API endpoints/methods.

Users

• get all users - parameters and responses

API Backends

• get all api backends - parameters and responses
• create new api backend - request and responses
• get api backend - responses
• update api backend - request and responses

Admin Accounts

• get all admins - parameters and responses
• create new admin - parameters, request, and responses
• get admin - responses
• update admin - request and responses

API Scopes

• get all API Scopes - parameters and responses
• create new API Scope - parameters, request, and responses
• get API Scope - parameters and responses
• update API Scope - request and responses

Admin Groups

• get all Admin Groups - parameters and responses
• create new Admin Group - parameters, request, and responses
• get Admin Group - parameters and responses
• update Admin Group - request and responses

[GUI]

The API docs are unfortunately quite incomplete, but here was an initial experiment I had made last year to stub some of the endpoints out with the API Blueprint spec: http://apiumbrella.io/docs/admin-api/

Here's the underlying blueprint page: https://github.com/NREL/api-umbrella/blob/master/website/docs/admin-api.blueprint.md (but I'm not really tied to API Blueprint, it was more that I had wanted to experiment with it at the time). And here's the source code for all the APIs that are intended to be public (basically anything under /api/v1): https://github.com/NREL/api-umbrella-web/tree/master/app/controllers/api/v1

It's been on my todo list for a long time to revisit this and actually finish writing the docs, but if you have any questions in the meantime, definitely feel free to reach out. Sorry the docs aren't more complete.

[brylie]

@GUI based on your response, I went ahead and renamed this task to be more specific regarding the work to be done. With your guidance, we can offer assistance with this task.

[brylie]

@GUI does the Gatekeeper also have an API? We would like to consider building some features on top of the Gatekeeper.

[GUI]

@brylie: All our web service API endpoints are currently app provided by the api-umbrella-web project, but a variety of those API endpoints end up affecting the gatekeeper once the configuration changes are persisted (since both components read from the same database for configuration). For example, the web component provides APIs to modify API backends, setup custom rate limits, etc, but then it's really the gatekeeper that reads in those changes and decides what to do with all that.

Or are you not referring to web service APIs, and are you referring more to a code API for the gatekeeper to implement plugins? In that case, our proxy layer does use connect middleware to layer most of it's functionality into place, so it should be compatible with most things written as a connect middleware.

Or if isn't what you're looking for, let me know if you have an example of the type of feature you're looking to build on top of the gatekeeper, and I can try to point you in the right direction.

[brylie]

We are planning a dashboard for API consumers and creators using the Meteor platform. Meteor has support for MongoDB and, experimentally, Redis, so I am researching how to use an existing database connection in a Meteor app.

What would be some strategies to loosely couple these applications -- basically to read/write configuration changes, user accounts, analytics, etc?

[brylie]

I have created an issue regarding integration options (#133), so that this issue can stay focused on API Umbrella Web API documentation.

[brylie]

@NRELAdmin and @GUI, I have updated this task description to include specific API endpoints and documentation needs. Please let me know if I can help this task move forward, as we are planning to develop software based on this API.

[brylie]

I am of the opinion that we should generate a Swagger and/or RAML description of the Admin API. Restlet Studio can be used for this process.

[brylie]

I do not fully understand the merits of either the Swagger or RAML specification, but do notice that Restlet Studio can import Swagger 2.0 and export both Swagger and RAML files. Also, Swagger has a nice user interface for displaying and sandboxing APIs.

[GUI]

Many apologies this has taken so long to get to. I've taken a first pass at documenting all of the admin API endpoints in Swagger here: http://apiumbrella.io/docs/admin-api/ The underlying swagger specification file is here: https://github.com/NREL/api-umbrella/blob/master/website/docs/admin-api-swagger.yml

Some of the fields could probably use some additional descriptions, and some error responses still need to be documented, but I think it should hopefully cover all the request parameters and response schemas for all the endpoints. But I haven't had time to fully audit or verify that everything matches up (trying to get something like SwaggerAssertions running would be nice to try to automatically verify this), so feel free to get in touch if anything seems amiss with this new documentation.

[GUI]

I think everything has been documented in the swagger spec, so I'm going to go ahead and close this, but let us know if anything still seems to be missing.