airtable.xq

A library for the Airtable Web API, using XQuery

Overview

The library module in the content directory contains functions for communicating with Airtable’s Web API 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 a personal access token or a service account access token from Airtable.

Web API functions

General

• airtable:get-user-info()

Base Data

Bases

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

Records

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

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 to conform to XQuery style conventions. 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 contributions to 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.

More recently, I've adopted the CI approach used by @duncdrum in aws.xq.

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.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. The default build target in build.xml is xar
3. Calling antin your CLI will build both files:

cd airtable.xq
ant

Since releases have been automated when building locally you might want to supply your own version number (e.g. X.X.X) like this:

ant -Dapp.version=X.X.X

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

Contributing

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

Release

Releases for this data package are automated. Any commit to the main branch will trigger the release automation.

All commit message must conform to Conventional Commit Messages to determine semantic versioning of releases, please adhere to these conventions, like so:

Commit message	Release type
fix(pencil): stop graphite breaking when too much pressure applied	Patch Release
feat(pencil): add 'graphiteWidth' option	Minor Feature Release
perf(pencil): remove graphiteWidth option BREAKING CHANGE: The graphiteWidth option has been removed. The default graphite width of 10mm is always used for performance reasons.	Major Breaking Release

When opening PRs commit messages are checked using commitlint.

License

AGPL-3.0 © Joe Wicentowski