Find out how to change the endpoint that is showing in the documentation

[gbinal]

Since all of the instances we stand up will include api.data.gov integration, we would like the ability to modify the url that is automatically generated in the API documentation to be the proxied api.data.gov url.

So, for instance, with this one, when you click Try it out, we'd want the Curl and Request URL fields to be https://api.18f.gov/sec/iardlist-2?api_key=DEMO_KEY instead of https://autoapi2.18f.gov/iardlist-2

cc @GUI, @jmcarp

[gbinal]

Possibly relevant:

autoapi/umbrella.py

Line 11 in 5adf204

base = 'https://api.data.gov/api-umbrella/v1'

[catherinedevlin]

@GUI has manipulated Swagger's base url before - talk to him

[GUI]

@catherinedevlin: So in Swagger V2 (which this is using), I think this is relatively straightforward (although that assumes it's easy for you to modify the Swagger, which hopefully it is, but if this is being generated by something else, it might require some digging). In any case, inside the top-level of the Swagger JSON structure (what's returned at https://autoapi2.18f.gov/swagger/), you'll need to introduce 2 new attributes, host and basePath (further docs). Those two variables should shift all the URLs used by Swagger around, so I think something like this should do the trick (and based on where I've used this before, I believe "basePath" will omit the trailing slash):

{
  "host": "api.18f.gov",
  "basePath": "/sec",
  ...
}

[GUI]

One additional note, though, is that it appears like this would be all that's necessary for the autoapi2.18f.gov instance, since it's only the Swagger documentation URLs that are incorrect. However, if the API itself returns any URLs (inside the response body), which the autoapi.18f.gov version does, then solving things is a little different (and perhaps a bit trickier). It sounds like the question of whether to use autoapi or autoapi2 might be up in the air (#44), but if the API returns any self-referencing paths or URLs (like autoapi.18f.gov's HATEOAS-looking API appears to), then the API itself will probably need to be updated in some fashion to alter those paths (api.data.gov doesn't modify the response bodies).

If that does come up, you'd basically need to check to see if the API is being accessed from behind a proxy, and if so, then alter the URLs being generated. I thought we passed back some useful HTTP headers from api.data.gov to aid with this, but it looks like we never quite got to this feature: 18F/api.data.gov#260 There are ways you could hard-code it based on the current headers we send back, but that isn't really ideal. So if you do end up needing to tackle this, give me a shout, and we can definitely get that implemented for you (it should be pretty quick and easy, and is something we need to do at some point anyway).

[catherinedevlin]

attach API key to swagger, too

[gbinal]

@GUI - any thoughts on where in the Swagger setup, we would put in an API key (likely DEMO_KEY1) so that the interactive documentation worked well instead of returning the API Key Needed error?

[GUI]

In Swagger V1 docs, we've treated this as an extra URL parameter with a default value assigned to DEMO_KEY. Here's an example: https://github.com/regulationsgov/developers/blob/gh-pages/api-docs/documents.json#L32-L39 (along with the live interface). I think Swagger V1 had some concept of authorization or an API key in the specification, but if I recall correctly, it was broken for a while in the swagger-ui project, so we ended up using this query string approach.

I haven't done this in Swagger V2 yet, but it looks like the schema supports a concept of an API key: http://swagger.io/specification/#securityDefinitionsObject However, it looks like perhaps it still wasn't quite functional in swagger-ui until quite recently (see swagger-api/swagger-ui#1593 and swagger-api/swagger-ui#2014). Theoretically, though, I think something like this in the swagger spec:

  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "name": "X-Api-Key",
      "in": "header"
    },
  },

should allow the user to specify their own key via the swagger-ui interface. However, I'm not sure if there's a simple way to set a default key like DEMO_KEY (I don't see anything obvious in their spec allowing this). You could probably force a default value with some javascript onload trickery. Alternatively, taking the same approach we took with Swagger V1 and just treating it as a normal URL query parameter with a default value should still work.

[gbinal]

You rule. Thank you.