search

transportapi / api-console

A Web Component for an interactive REST console based on RAML files
Other
0 stars 0 forks source link

unnecessary long url with raml= parameter #4

Open harry-wood opened 8 years ago

harry-wood commented 8 years ago

Currently the documentation is at http://docs.transportapi.com/index.html?raml=http://transportapi.com/v3/raml/transportapi.raml#

It would be better if this worked at http://docs.transportapi.com/

It shouldn't be necessary to specify the raml parameter. Can't we hardcode that behind the scenes?

madwort commented 8 years ago

It isn't necessary to specify the parameter to reach the docs - there is a redirect from http://docs.transportapi.com/ to http://docs.transportapi.com/index.html?raml=http://transportapi.com/v3/raml/transportapi.raml# - but it's not necessarily simple to hardcode it behind the scenes because it's not a real get param, it's a virtual get param that is actually being read by the javascript. So all we could do would be to iframe the whole lot, and then you lose the ability to deep link into the docs.

harry-wood commented 8 years ago

Yes please no iframes. You mentioned iframes. Let's never mention iframes again :-)

I've tried to describe a few problems without describing the fixes much, but I think this, and some of the other issues I'm raising, are pointing in the direction of making some tweaks to the javascript and maintaining these tweaks as a fork of the api-console codebase. So I suppose I mean hardcode the raml URL in the javascript.

madwort commented 8 years ago

Ok. We did see discuss trying to hide this param when we deployed it, but couldn't see a quick/good fix.

The other complication is that there was an idea from the business team that we would have custom endpoints only available on certain customers' enterprise instances. So what we did was deployed an api-console on its own url for each of the enterprise customers. So we can't just hardcode the raml url, we have to parameterise it for enterprise instances, e.g. http://docs.fcc.transportapi.com/index.html?raml=http://fcc.transportapi.com/v3/raml/transportapi.raml or go back to the business team & discuss whether we can drop this requirement for customer-specific endpoints & docs (which I don't think we've ever actually done anyway).

harry-wood commented 8 years ago

Yeah. Also I have used this parameter to point people at changes to RAML docs running on a webrick server.

So the thing to do would be to hardcode a default value, so that most users of docs get a less messy URL, but retaining the ability to set the parameter