Green Thumb Software

ActionKit-API-Fetch: Documentation

Introduction
Documentation
Examples

ActionKit dashboard reports are traditionally used to aggregate and reformat the results of SQL queries — but they can also be used to build useful interactive tools that invoke the API from within the admin interface.

To make it easier for folks to build such dashboards, I am sharing akapi-fetch.js, a small JavaScript library that makes it easier to call the AK API and process its results in this context.

All examples shown below are written for use inside an ActionKit dashboard report.

Integration

To load akapi-fetch.js, you can load a copy of the library from this site, or you can make a copy of the library and host it elsewhere, such as your instance’s S3 bucket.

<script src="https://greenthumbsoftware.com/akjs/akapi-fetch.js"></script>

However, in practice, we typically will want to run a bunch of JavaScript code as soon as that library has been loaded; since the ActionKit admin interface loads jQuery, we can use the simple idiom it provides for this: 

<script>
  $.getScript( 'https://greenthumbsoftware.com/akjs/akapi-fetch.js' )
  .then( async function () {
    ...
  } );
</script>

Request Methods

Once the library is loaded, you can issue requests and wait for their results using the following method:

results = await akapi.fetch( method, path, params, options );

The method can be any of the values supported by the ActionKit API — GET, POST, PATCH, PUT, DELETE — or you can specify those methods by calling one of these named methods:

results = await akapi.get( path, params );
results = await akapi.post( path, params );
results = await akapi.patch( path, params );
results = await akapi.put( path, params );
results = await akapi.delete( path, params );

Results

Depending on the path and method, the results will either hold a representation of the relevant resources, or the URL for a resource that has been created or updated, or a request status code such as 202. In general, the method dictates the results you can expect:

  • Get: An object representing a single record, or a collection of records.
  • Post: The URL for a newly-created record.
  • Patch: A 202 success status code.
  • Put: A 204 success status code.
  • Delete: A 204 success status code.

See the ActionKit documentation for additional details on response types.

Call Options

The options argument is usually omitted, but when needed you can provide a reference to an object with values for one or both of these keys:

  • cache: Pass a true value to have the results of the request cached and reused if you issue the same request again in the future.
  • receive: Pass “html” to retrieve report results as formatted HTML instead of raw data.

There are also wrapper methods that enable those option:

results = await akapi.get_cached( path, params );
results = await akapi.get_html( path, params );
results = await akapi.post_html( path, params );

Callback Invocation with Then

As shown by the use of await above, the request methods operate asynchronously, returning a promise which will be resolved when a response is received from the server.

If you don’t want to use JavaScript’s async / await syntax, you can also invoke these methods and set up callbacks using the Promise / then syntax:

akapi.get( path, params ).then( function ( results ) { ... } );

These two approaches are equivalent, but the async syntax is a bit simpler, so I will use it in most of the below examples.

Configuration Parameters

There are three global parameters you can set to change the library’s behavior:

akapi.allow_writes = [ true | false ]
akapi.console_logging = [ true | false | 2 ]
akapi.alert_on_failure = [ true | false ]

All of these parameters default to true, but can be overridden as follows:

  • Set allow_writes to false to cause an exception on POST/PATCH/PUT requests.
  • Set console_logging to false to disable the default logging of API requests to the browser console, or set it to 2 to cause the logging to include the values of responses.
  • Set alert_on_failure to false to disable the default use of browser alerts to notify the user of a failed API request.

Error Handling

As noted above, by default akapi-fetch.js pops up a browser alert if an API call fails. You can override that behavior and provide your own error handling as shown below:

akapi.alert_on_failure = false;
try {
    result = await akapi.get( path, params );
} catch {
    ... something went wrong ...
}

Sample Usage

You can see these methods in use in the examples page.