A library for the Airtable REST API and Metadata API, using XQuery
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
Metadata API functions
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.)
The library uses standard XQuery 3.1, but is dependent on eXist in two areas:
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.
To prevent hitting the Airtable API’s rate limits, we use eXist’s
cachemodule 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
cache functions to those of your processor.
- 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.
1.10.7(for building from source)
12.x(for building from source)
airtable.xq-1.0.3.xarfile from GitHub releases page.
Open the Dashboard on your eXist-db instance and click on
- Click on the
Uploadbutton in the upper left corner and select the
.xarfile you just downloaded.
- Click on the
You have successfully installed airtable.xq into eXist.
Building from source
Download, fork or clone this GitHub repository
There are two default build targets in
devincluding all files from the source folder including those with potentially sensitive information.
deployis the official release. It excludes files necessary for development but that have no effect upon deployment.
antin your CLI will build both files:
cd airtable.xq ant
- to only build a specific target call either
If you see
BUILD SUCCESSFUL ant has generated a
airtable.xq-*.xar file in the
build/ folder. To install it, follow the instructions above.
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.
This app uses cypress for integration tests, just type:
npm run cypress
Alternatively, use npx:
npx cypress open
You can take a look at the Contribution guidelines for this project
AGPL-3.0 © Joe Wicentowski