Static API Documentation with embedded API key

Question

I'm setting up the API documentation for a project, and wanted to know what the best tool for the job is..

The site is completely static EXCEPT for the API keys, which I'd like to include in the code examples depending on the user (the user gets their own API key if they're logged in).

How can I achieve this, while maintaining a static site (I'm using a static-site generator, middleman).

Where do API keys originate from? Do you have a backend with and API that can be used to retrieve API keys? Can you authenticate against that backend? — Andrey Mikhaylov - lolmaus, Oct 29 '14 at 07:07
@lolmaus-AndreyMikhaylov They could be retrieved from the API itself (through a public endpoint as suggested in the answer below). As it stands, I'm retrieving the API key from the database after validating the session (the API and website share the same codebase) — FloatingRock, Oct 29 '14 at 08:32
Middleman is a static site generator, it won't help you access the API. I suggest that you file your question against `javascript`, `jquery`, etc tags instead of `middleman`. You have to figure out how to authenticate a site visitor against the API using JS, then retrieve the keys from the API, then inject them into the page. — Andrey Mikhaylov - lolmaus, Oct 29 '14 at 08:34
So... How does the user authenticate against the API in order to determine whether he's allowed to see the keys? — Andrey Mikhaylov - lolmaus, Oct 29 '14 at 08:50
Uhm... The user has to provide some credentials to the API, otherwise any visitor could view any user's keys, right? — Andrey Mikhaylov - lolmaus, Oct 29 '14 at 08:55
Have a look at this: http://stackoverflow.com/questions/2870371/why-is-jquerys-ajax-method-not-sending-my-session-cookie — Andrey Mikhaylov - lolmaus, Oct 29 '14 at 08:57
@lolmaus-AndreyMikhaylov thanks -- it'll definitely be on the same domain. The issue you raised is valid; if i have your `_session` then I would be able to get your test keys. Sounds bad .. you think a nonce should be used too? (doesn't Rails do that automatically?) — FloatingRock, Oct 29 '14 at 08:58
Okay, so Rails come into play. I guess that if your static site is on the same domain, then you should be able to do simple ajax call to the API. Oh, i see you have already accepted the answer suggesting that. Well, good luck! — Andrey Mikhaylov - lolmaus, Oct 29 '14 at 09:00

score 2 · Accepted Answer · answered Oct 28 '14 at 09:08

2

I would suggest you to include small ajax script on all pages, which will perform search-and-replace through the page.

On the static page you will have code like this:

<!-- EMPTY SPAN IN PAGE TEMPLATE -->
<span class='api-key'></span>

everywhere you want to have api keys embedded. The script will perform the simple task of search-and-replace (pseudocode follows, assuming you have jQuery on the page):

$(document).ready(function () { 
  $.get( "/api/key", function( data ) { /* supply credentials if needed */
    $('.api-key').html( data ); 
  }
});

Hope it helps.

answered Oct 28 '14 at 09:08

Aleksei Matiushkin

119,336
10
100
160

Thanks, I'm not aware of any API that exposes an endpoint for API key generation. Do you know of any? In any case, I presume I would need to pass some sort of cookie from the client in the request .. how would that work? – FloatingRock Oct 28 '14 at 09:43
You wrote “_the user gets their own API key if they're logged in_” what in my opinion means you already have kinda authorization implemented, right? This authorization code might expose simple interface returning `api-key` for logged in users and null for guests. – Aleksei Matiushkin Oct 28 '14 at 09:55
Session-based authorization is done, with a domain cookie on the client browser. You don't have to be authenticated to view the static documentation page. The only way it'd be able to tell is through the Cookie. When you do `$.get` does it pass the domain cookie along? If not, how could it be setup to automatically pass the (encrypted) cookie to the server for evaluation -- after which it would return the Api Key for the user? The cookie is generated by Rails, and the API is rails too. – FloatingRock Oct 28 '14 at 13:48
Every request to the server passes cookie along, including image and resource retrieval. – Aleksei Matiushkin Oct 28 '14 at 14:04
Thanks, so I would need to figure out how to extract the session from the cookie, retrieve the relevant API key (if signed in), or generate a test key (if not signed in). I'll give that a shot.. If you have any pointers/examples of this being done in the wild, please share. Thanks – FloatingRock Oct 29 '14 at 08:30
1

I don’t think you need to extract session from the cookie (besides it might be not possible on client side.) I would implement 1 server handler (say, at `/api/get/key` or at the URI you like,) which would be responsible for auth verification, returning either key or stub. – Aleksei Matiushkin Oct 29 '14 at 08:46
Yeah, that sounds like the way to go. Thanks – FloatingRock Oct 29 '14 at 08:47

Static API Documentation with embedded API key

1 Answers1