Moving beyond built-in knowledge of host-specific issue stores

[wking]

I'd like to link #54 to the relevant Firefox and Chromium issues, and that cross-host referencing is explicitly one of our targets (supports multiple websites). Information we need to crawl a dependency:

1. Which ecosystem the issue-store lives in (e.g. HTTP(S))?

   • Within HTTP(S):

     1. Which host provides the API exposing the issue (e.g. bugzilla.mozilla.org)?

2. Which API the host provides (e.g. the Bugzilla REST API)?

3. Which logo to use on the card?

The current /{protocol}/{host}/{api-params} approach covers the ecosystem and host bits fairly well, but we currently hard-code the API and logo by host. Because things like Bugzilla, monorail, and even GitHub (with enterprise installs) allow the same API to be supported by several hosts, depviz will scale better if we drop that hard-coding and discover the intended API more dynamically.

One approach would be to push this to the user, with a general URL template like:

/{protocol}/{api}/{params}

with the HTTP(S) case breaking {params} down into {host-basepath}/{api-params}. So we'd have URLs like:

• /http/github/api.github.com/jbenet/depviz/54 (https://api.github.com/repos/jbenet/depviz/issues/54)
• /http/bugzilla/landfill.bugzilla.org%2Fbugzilla-5.0-branch/37782 (https://landfill.bugzilla.org/bugzilla-5.0-branch/rest/bug/37782)
• /http/bugzilla/bugzilla.mozilla.org/866522 (https://bugzilla.mozilla.org/rest/bug/866522)

That's nice and explicit and it will scale well to new installations of already-supported APIs, but users are not going to be able to copy-paste cleanly.

Sometimes the mapping between the browsable issues and the API root is clear. E.g. for Bugzilla it's under {host-basepath}/rest and for enterprise GitHub installs, the API is under {host-basepath}/api/v3 (but for GitHub itself, you have to replace the browsable github.com with api.github.com). If we feel like that's reliable enough, we could hard-code the special cases and use /http/github/github.com/jbenet/depviz/54 instead of /http/github/api.github.com/jbenet/depviz/54.

Sometimes the API is discoverable. E.g. for Bugzilla you can hit the version endpoint and see if it looks Bugzilla-ish (although unfortunately it does not actually say bugzilla in the response). For GitHub you can hit the meta endpoint. If we feel like that's reliable enough, when depviz hits a new host we could iterate through known APIs looking for a match (and store the host/API pair in local storage).

If we hava a reliable browsable host-basepath → API host-basepath translator and a reliable API implementation detector, and we're comfortable polling with that implementation detector, we could drop the {api} portion and get back to our current:

• /http/github.com/jbenet/depviz/54
• /http/landfill.bugzilla.org%2Fbugzilla-5.0-branch/37782
• /http/bugzilla.mozilla.org/866522

with straightforward redirects to remove issues/ or show_bug.cgi?id= and other boilerplate. Folks using landfill.bugzilla.org/bugzilla-5.0-branch would still not be copy/pastable, but I don't see a way around that without an API-agnostic way to separate basepath from api-params.

Figuring out which logo to use is less important (for HTTP(S) we can always fall back to favicons), but I thought I'd list it for completeness. It would be nice if browsable issue-stores supported a well-known URL exposing this API/API-root/logo information for us :p.

[wking]

And to pick another example from #54, the w3c is also running Bugzilla (v5.0.3 at https://www.w3.org/Bugs/Public/). For some reason they seem to have disabled their REST API (all my attempts 404), but JSONRPC requests like this work.