API, съвместимо с Airtable
Artavolo отговаря на REST API на Airtable на същите пътища, така че скрипт, SDK-то Airtable.js или HTTP стъпка, написани за Airtable, продължават да работят след две промени: адреса и токена.
const Airtable = require('airtable')
const base = new Airtable({
apiKey: process.env.ARTAVOLO_TOKEN, // an Artavolo API token
endpointUrl: 'https://artavolo.com', // instead of https://api.airtable.com
}).base('appXXXXXXXXXXXXXX') // the same base id as in Airtable
curl -H "Authorization: Bearer $ARTAVOLO_TOKEN" \
"https://artavolo.com/v0/appXXXXXXXXXXXXXX/Tasks?filterByFormula=%7BStatus%7D%3D'Done'"
Токенът е API токен на Artavolo (Профил, API токени), изпратен като Authorization: Bearer <token> (или с Basic автентикация, или в заглавката API-KEY, както при API за данни). Неговият член действа със собствените си права: ролите, видимостта на таблиците и правилата за редове важат, всеки запис е в дневника на промените, изтриванията отиват в кошчето, а уебхуковете и автоматизациите се изпълняват както при всяка друга промяна.
Идентификатори
| Airtable | Тук |
|---|---|
база app... | идентификаторът от Airtable, от който е внесена базата, или кодът на базата в Artavolo |
таблица tbl... | идентификаторът от Airtable, с който е внесена, нейното име или нейният идентификатор в Artavolo |
поле fld... | идентификаторът от Airtable, с който е внесена, или нейното име |
запис rec... | идентификаторът от Airtable, с който е внесен; запис, създаден в Artavolo, има recAV и своя идентификатор в основа 36 (дванадесет знака) |
Така връзките, скриптовете и запазените идентификатори на записи, направени в Airtable, продължават да сочат към същите записи след импорт.
Маршрути
| Метод | Път | |
|---|---|---|
| GET | /v0/{base}/{table} | списък със записи |
| POST | /v0/{base}/{table}/listRecords | същото, с параметрите в тялото |
| GET | /v0/{base}/{table}/{record} | един запис |
| POST | /v0/{base}/{table} | {fields} или {records: [{fields}]}, най-много 10; typecast се приема |
| PATCH | /v0/{base}/{table}/{record} или /v0/{base}/{table} | {fields} или {records: [{id, fields}]}, най-много 10 |
| PUT | същото | като PATCH, като непосочените полета се изчистват |
| DELETE | /v0/{base}/{table}/{record} или /v0/{base}/{table}?records[]=... | най-много 10; отговаря с {id, deleted: true} / {records: [...]} |
| GET | /v0/meta/whoami | човекът зад токена: {id, email, name} |
| GET | /v0/meta/bases | базите, които токенът може да отваря: {bases: [{id, name, permissionLevel}]} |
| GET | /v0/meta/bases/{base}/tables | {tables: [{id, name, primaryFieldId, fields: [{id, name, type, options}], views}]}, типовете полета както ги именува Airtable |
| POST, GET, DELETE | /v0/hooks[/{id}] | абонаменти за промените в таблица, за Zapier, Make и n8n: вижте интеграциите |
Листингът приема pageSize (най-много 100), offset, maxRecords, fields[], sort[0][field] и sort[0][direction], view (по име или идентификатор: прилагат се неговият филтър и сортиране), filterByFormula и returnFieldsByFieldId. За периодично опресняване (polling) има три добавки, собствени за Artavolo: sort[0][field]=CREATED_TIME() или LAST_MODIFIED_TIME() (не е нужно поле за време), createdAfter и modifiedAfter (ISO време, без включване на границата) и recordMetadata[]=lastModifiedTime, което добавя lastModifiedTime до createdTime. Стойностите са в JSON клетъчния формат на Airtable: единичен избор като името на опцията, множествен избор като имена, връзки като идентификатори на записи, прикачени файлове като {id, url, filename, size, type}, сътрудник като {id, email, name}, отметка като true или пропусната, дати като YYYY-MM-DD или ISO дата и час. Празните полета се пропускат, както прави Airtable.
filterByFormula
Частта, на която сървърът може да отговори точно: сравнения на поле със стойност (=, !=, <, >, <=, >=), AND, OR, NOT, FIND, SEARCH, BLANK(), TRUE(), FALSE(), IS_BEFORE, IS_AFTER, IS_SAME и RECORD_ID(). Всичко друго връща на Airtable 422 INVALID_FILTER_BY_FORMULA, никога по-широк списък.
Все още не
performUpsert (422, казано ясно: потърсете записите с filterByFormula, след това ги създайте или обновете), промяна на схема през API за метаданни (то само чете), собственото API за уебхукове на Airtable (/v0/bases/{base}/webhooks, с неговите данни, базирани на курсор; абонаментите вършат тази работа тук), коментари към записи през /v0, cellFormat=string.
Грешки
Както ги пише Airtable: {"error": {"type", "message"}} с 401 AUTHENTICATION_REQUIRED, 403 INVALID_PERMISSIONS_OR_MODEL_NOT_FOUND, 404 NOT_FOUND, 422 INVALID_REQUEST_UNKNOWN, UNKNOWN_FIELD_NAME, INVALID_VALUE_FOR_COLUMN, INVALID_FILTER_BY_FORMULA. Над лимита на заявките (600 в минута на токен и 3 000 на работно пространство в хостваната услуга; вижте ограниченията) отговорът е 429 TOO_MANY_REQUESTS със заглавка Retry-After, като собствения 429 на Airtable.
Експорт обратно към Airtable
GET /api/v2/bases/{code}/tables/{id}/export?format=airtable-csv
GET /api/v2/bases/{code}/tables/{id}/export?format=airtable-json
За всеки, който може да чете таблицата. CSV е това, което чете собственият CSV импорт на Airtable: заглавен ред с имена на полета, множествени избори, съединени със запетаи, отметка като checked, връзки чрез основните стойности на свързаните записи, прикачени файлове като filename (url); клетка, която електронна таблица би изпълнила като формула, започва с апостроф. JSON е във формата на списъка от /v0, всеки запис. Напускането е толкова лесно, колкото пристигането.
Тестове: tests/airtable_v0_test.php, tests/integrations_test.php (мета API, polling, абонаменти).