Available APIs listing

[brylie]

Story

As a Developer (API Consumer) I would like a page to list details available APIs So that I can determine which APIs I can use

Example usage

I want to view available APIs, so I

1. Access the API Umbrella portal
2. Click a link to view available APIs
3. Determine how to access the desired APIs (i.e. whether an API key is necessary)

   Dependencies

   • Pre-configured APIs (already set up by API Manager)
   • Authorization

[kyyberi]

Should be rather straight forward to list from database with Rails

[brylie]

I updated the ticket to make it more apparent that the list should be based on authorized access. I.e. some APIs may be private, some may need specific access permissions, etc.

[GUI]

So I think we currently have a slightly different approach to API listings than what you might be looking for. Currently, we maintain our public listing of APIs independently from the list of "API Backends" that you configure in the admin. In our case, the public listing of APIs isn't actually stored in the database at all, but is instead just some static website content (see https://github.com/NREL/api-umbrella/issues/69#issuecomment-63920367 for some more detail on how we currently manage our website content).

Our current approach stems from the fact that one "API Backend" configured in the admin is often responsible for many public APIs we want to list. As a quick example, on api.data.gov, there is one "API Backend" to route all of the National Renewable Energy Laboratory's APIs to the appropriate endpoint. However, from an API listing perspective, we want to list all the APIs individually, as you can see here: https://api.data.gov/docs/nrel/ (associated website source code).

I guess we've seen the API listings more of a content management issue, and not necessarily something we've wanted to tie to the "API Backends" or tackle separately in the admin. Actually, the admin did used to provide a little mini-CMS for managing API listings and documentation a couple years ago, but we got rid of it, because we felt like the documentation could be better managed in real CMSes or other tools. We opted for a simple static site generator for our documentation and API listings, but you could also use API Umbrella in conjunction with a more full-fledged CMS.

Now, this approach certainly stems from our use-cases, which might be very different from yours. So I'd certainly be interested to hear more. Do you think using a separate content management tool could work well for your API listing, or do you think something more tightly integrated with API Umbrella would make more sense for you?

[brylie]

Intuitively, I am thinking that an automatic listing would be useful for a few reasons:

• reduce duplicate effort/maintenance
• reduce duplicate information
• reduce possible errors stemming from duplication

This automated listing could also take care of permissions, i.e. showing only relevant api endpoints, by integrating with API Umbrella ACL rules.

From a bigger picture perspective, we are considering possibilities of automating many aspects of API lifecycle management, including automatic configuration, using explicit API specification files (e.g. with the RAML).