Customising the API explorer

The apiExplorer JavaScript object provides a method to add API keys to an internal list, and a method to inject those API keys into the explorer page, so that the user can select the key from a drop-down menu instead of having to type it in.

By default, the template fragment assets/themes/default/templates/fragments/scripts.tmpl (shown below) controls the handling of authentication credentials for the explorer:

<!-- Additional scripts to be loaded at end of page 
  -- This should be overridden to take control of the auth process (adding keys to the explorer request).
  -->
<script>
   $(document).ready(function(){
        // Register callback to add authorisation parameters to request before it is sent
        apiExplorer.setBeforeSendCallback( function( request ) {
            var apiKey      = apiExplorer.readApiKey();      // Read API key from explorer input
            var accessToken = apiExplorer.readAccessToken(); // Read access token from explorer input
            var basicAuth   = apiExplorer.getBasicAuthentication(); // Create basic auth string

            // Favour access tokens over api keys
            if( accessToken != "" ) { request.headers = {Authorization: "Bearer "+accessToken}; }
            else if( apiKey != "" ) { request.params  = {key: apiKey}; }
            else if( basicAuth != "" ) { request.headers = {Authorization: "Basic "+basicAuth}; }
        });
    });
</script>

It would be usual for this template fragment to be overridden by an installation, so that a list of valid API keys can be built and injected into the explorer page. This allows a user of the explorer to select an API key from a menu, to be used in the request. Generally the keys would be fetched from some AJAX endpoint that you provide, once the user as gone though some sign-in process.

Controlling authentication credential passing

The example examples/apikey_injection/assets/templates/fragments/scripts.tmpl shows how the default scripts.tmpl can be overridden to inject an API key (hard-coded for the benefit of this example), as a list-of-one into the explorer page:

<!-- Inject API key(s). This would probably be done via an ajax request to a server to request the API
     keys for the signed in user.
     Register callback to appropriately add the authentication credentials (as a Basic auth header)
     to the request before it is sent.
  -->
<script type="text/javascript">
    $(document).ready(function(){
        apiExplorer.addApiKey("A test key","2jnD1-ZnGBsT2ST7mSm9ASaGxO7BPWU4iz9TlfE6");
        apiExplorer.injectApiKeysIntoPage();

        // Register callback to add authorisation parameters to request before it is sent
        apiExplorer.setBeforeSendCallback( function( request ) {
            var apiKey = apiExplorer.readApiKey(); // Read API key from explorer input
            // Set the API key in the request as an Authorization header, using BASIC authentication
            request.headers = {Authorization:"Basic " + btoa(apiKey + ":")};
        } );
    });
</script>

To run this example, DapperDox needs to be told about the example assets directory for it to pick up the override. This is achieved through the configuration parameter -assets-dir, passed to DapperDox when starting:

-assets-dir=examples/apikey_injection/assets

By default, DapperDox will automatically attach the API key if supplied, to the request URL as a key= query parameter. This behaviour can be customised to satisfy the authentication requirements of your API.

The template fragment assets/themes/default/templates/fragments/scripts.tmpl, which is included at the end of the common page template layout.tmpl contains the following JavaScript snippet:

apiExplorer methods

The API explorer object apiExplorer provides a number of methods:

Setting headers and query parameters

The javascript examples on this page register a callback via the explorer method apiExplorer.setBeforeSendCallback(), which gets invoked while the explorer is building the request to send to the API. The callback will be receive an empty object which has two properties that can be set as needed, request.headers - items that are sent as request HTTP headers, and request.params - items that are sent as query parameters:

{
    headers: {},
    params: {}
}

Both the headers and params objects contain zero or more name/value pairs:

{
    key1: value,
    ..
    ..
    key_n: value_n
}

For example:

request.headers = { header: "value" };
request.headers = { header1: "value1", header2: "value2" }

To put this into practice, if you wanted to change the authentication credential passing mechanism to instead supply the API key as an Authorization header, then create a scripts.tmpl within your own assets directory to override this. For example, the DapperDox example file examples/apikey_injection/assets/templates/fragments/scripts.tmpl passes the API key in the Authorization header using BASIC authentication:

$(document).ready(function(){
    // ... other code cut from here ...

    // Register callback to add authorisation parameters to request before it is sent
    apiExplorer.setBeforeSendCallback( function( request ) {
        var apiKey = apiExplorer.readApiKey(); // Read API key from explorer input
        request.headers = {Authorization:"Basic " + btoa(apiKey + ":")};
    });
});

DapperDox then needs to be told about this local assets directory for it to pick up the override, which is achieved through the configuration parameter -assets-dir, passed to DapperDox when starting. For example, to pick up the example above, use -assets-dir=examples/apikey_injection/assets.

See Authoring content and associated pages for further information about creating custom assets.