airtable.xq

A library for the Airtable REST API and Metadata API, using XQuery

Overview

The library module in the content directory contains functions for communicating with Airtable’s REST and Metadata APIs via XQuery. To use the library module, either import it directly from the content directory, or install or build the package and import the library module with:

import module namespace airtable="http://joewiz.org/ns/xquery/airtable";

The library contains the following functions, all of which require an API Key from Airtable. The two functions that access Airtable’s Metadata API require an additional token from Airtable.

Rest API functions

• airtable:create-records()
• airtable:retrieve-record()
• airtable:list-records()
• airtable:update-records()
• airtable:delete-records()

Metadata API functions

• airtable:list-bases()
• airtable:get-base-tables-schema()

How it works

The library sends requests to the Airtable API using the EXPath HTTP Client library. (See eXist notes below.)

Successful responses (with status 200) are returned with the response body’s JSON object parsed as a map.

When a response indicates an error (a non-200 status), the library’s functions all return a map with an "error" entry, with subentries to aid in debugging: request, response head and body, rate limit assessments, start and end dateTimes, and duration in seconds.

Function documentation is adapted from the Airtable API for XQuery context and style (XDM terminology replaces JSON terminology, and parameters are kebab case rather than camel case.)

XQuery compatibility

The library uses standard XQuery 3.1, but is dependent on eXist in two areas:

1. eXist’s EXPath HTTP Client module returns JSON as xs:base64Binary, so util:binary-to-string() is always needed before the JSON can be parsed.

2. To prevent hitting the Airtable API’s rate limits, we use eXist’s cache module to store the dateTime of the last request. If a delay is needed before a request can be submitted, the util:wait() function is used.

To adapt the library to another processor, you may adapt these util and cache functions to those of your processor.

Caveats

• The "typecast" parameter for automatic data conversion for list, create, and update actions hasn’t been implemented.
• No special handling for User and Server error codes except rate limits; instead, full HTTP response headers are returned.

About this repository

Thanks to @duncdrum for his generator-exist tool, which generated all of the scaffolding for this app—EXPath package descriptors, GitHub templates, and GitHub Actions actions. I used the "blank" template. I've made only minimal changes to the assets generated by this tool.

Requirements

• eXist-db version: 5.0.0 or greater

• ant version: 1.10.7 (for building from source)

• node version: 12.x (for building from source)

Installation

1. Download the airtable.xq-1.0.3.xar file from GitHub releases page.

2. Open the Dashboard on your eXist-db instance and click on Package Manager.

   1. Click on the Upload button in the upper left corner and select the .xar file you just downloaded.

3. You have successfully installed airtable.xq into eXist.

Building from source

1. Download, fork or clone this GitHub repository

2. There are two default build targets in build.xml:

   • dev including all files from the source folder including those with potentially sensitive information.

   • deploy is the official release. It excludes files necessary for development but that have no effect upon deployment.

3. Calling antin your CLI will build both files:

cd airtable.xq
ant

1. to only build a specific target call either dev or deploy like this:

ant dev

If you see BUILD SUCCESSFUL ant has generated a airtable.xq-*.xar file in the build/ folder. To install it, follow the instructions above.

Running Tests

To run tests locally your app needs to be installed in a running exist-db instance at the default port 8080 and with the default dba user admin with the default empty password.

A quick way to set this up for docker users is to simply issue:

docker run -dit -p 8080:8080 existdb/existdb:release

After you finished installing the application, you can run the full testsuite locally.

Unit-tests

This app uses mochajs as a test-runner. To run both xquery and javascript unit-tests type:

npm test

Integration-tests

This app uses cypress for integration tests, just type:

npm run cypress

Alternatively, use npx:

npx cypress open

Contributing

You can take a look at the Contribution guidelines for this project

License

AGPL-3.0 © Joe Wicentowski