search

ExchangeBC / BCDevExchange-app

The BCDevExchange website is the public facing site for the BC Developers' Exchange - an experiment in tech innovation and collaboration. *NOTE: This repo is deprecated* and retained only for archival/informational purposes. The repo containing the current BC Developers' Exchange app is https://github.com/bcdevexchange/devex. Head over there to see the latest code.
Apache License 2.0
24 stars 12 forks source link

API listing service #203

Closed paulroberts68 closed 8 years ago

paulroberts68 commented 8 years ago

As a program owner I would like to list my API with the exchange so that developers can find my API through the exchange listing service

Assumptions

The exchange currently uses WSO2 for API management, including listing service. WSO2 forces all listed APIs to use its gateway endpoint - a constraint that is unacceptable by some clients. To resolve, listing service should be implemented independently from API gateway.

Task Description

  1. Create an API registration web form. Key information captured by the web form is swagger URL. The web form is accessible by program owners.

  2. Create/display a searchable list that aggregates data sources from:

    1. Manually registered by a program owner using the web form.
    2. Pre-configured RESTful data sources, such as BCDC, which should be able to provide the swagger URL at least as an optional field.
    3. The new API gateway to be implemented by exchange.

    All information in the swagger file should be searchable. The list should contain links to the details page described below if swagger is available, or external references otherwise.

  3. Create API details page modeled after WSO2 that provides a tabbed view of:
    1. API console: This is the swagger explorer. Note BCDevExchange has an api explore available at https://bcdevexchange.org/api-explorer/<swagger_url> so this tab can be implemented as an iframe.
    2. Documentation: This is the information provided by swagger 2.0 external documentation object
    3. Throttle Info: This tab is only visible if data source is BCDevX API gateway.
gjlawran commented 8 years ago

As a BC government API contributor I would like my API, that I have already listed in the BC Data Catalogue, to automatically appear in the BCDevExchange API list, so that I don't have to maintain information about my API in two places.

f-w commented 8 years ago

@gjlawran, bcdevx API listing service will require swagger url for each api. Can BCDC meet this requirement?

gjlawran commented 8 years ago

@f-w swagger definitions do not exist for most APIs - worldwide - however, of the APIs currently registered in BCDC a couple have partial Swagger definitions. We don't have consistent place to store the swagger URL in BCDC - the requirement for a swagger definition was not raised by contributors or consumers in requirements - however we could easily appropriate the more info URL element for that purpose.

@paulroberts68 is there a requirements doc / story for the API list? Perhaps there are other things that we should be referencing / capturing.

f-w commented 8 years ago

@gjlawran, I am trying to make bcdevx API listing service beyond the capability of shallow referring-only so that developers can go straight to the consistent API "try it out" console UI without jumping the hoops. I see Swagger is the means to achieve this ends.

gjlawran commented 8 years ago

@f-w absolutely, having a console UI for developers to more quickly, and more likely, engage with the API should be encouraged.

Just not sure if DevEx wants to bar the door to entry for those APIs that can't yet provide a valid swagger definition.

Certainly highlighting those APIs that can provide one, and giving them incentive via a rich console experience, and even providing them with an easy editor are all great ways to encourage that - but not allowing them in the door in the first place seems like an opportunity lost.

We try to do the same thing with data. We don't turn away data if it isn't just available via an API. Having it available via an API may be great, but having the data first and foremost is the objective.

f-w commented 8 years ago

@gjlawran , does or can BCDC capture swagger URL in registration form, even if the field is optional? Otherwise if BcDevX includes BCDC data, then the API provider will tend to manually register the API swagger to BCDevX, resulting in duplicated entries.

gjlawran commented 8 years ago

BCDC can capture swagger URL in registration form. BCDC could also store the YAML/JSON itself vs. hosted at an external location - e.g. GitHub, GitLabs. Not sure what the best practice might be in this regard.

On Mon, Nov 30, 2015 at 11:41 AM, Fred notifications@github.com wrote:

@gjlawran https://github.com/gjlawran , does or can BCDC capture swagger URL in registration form, even if the field is optional? Otherwise if BcDevX includes BCDC data, then the API provider will tend to manually register the API swagger to BCDevX, resulting in duplicated entries.

— Reply to this email directly or view it on GitHub https://github.com/BCDevExchange/BCDevExchange-app/issues/203#issuecomment-160736717 .

paulroberts68 commented 8 years ago

@gjlawran There are a couple of stories that have materialized as a result of some research (201 and 200). Ideally we need to conduct a UX workshop to determine/refine/confirm the features that the exchange users actually want from a listing service and @ragbay @lmullane would be able to help us create this. The API listing service is not a priority for this sprint but we could attempt some research between the 18th Dec through 24th (or before capacity permitting).

kelpisland commented 8 years ago

I'm closing this issue as much of the acceptance criteria is complete. I'm going to open a new issue to capture Paul's final comment.