This is a Java API client for Airtable (http://www.airtable.com).
The Airtable API provides a simple way of accessing data within Java projects.
More information about the Airtable API could be found at https://airtable.com/api. The documentation will provide detailed information about your created base.
For adding dependency, you could use bintray-repository: https://bintray.com/sybit-education/maven/airtable.java
The files are stored at: https://dl.bintray.com/sybit-education/maven/
For Gradle add compile com.sybit:airtable.java:[version] to compile dependencies.
Also add repository to dependencies:
repositories {
maven {
url = uri("https://maven.pkg.github.com/Sybit-Education/airtable.java")
...
}
}
It is required to initialize the Java API before it is used. At leased you have to pass your API-Key to get access to Airtable:
Airtable airtable = new Airtable().configure();The API key could be passed to the app in different ways:
- Defining Java property
AIRTABLE_API_KEY(e.g.-DAIRTABLE_API_KEY=foo). - Defining OS environment variable
AIRTABLE_API_KEY(e.g.export AIRTABLE_API_KEY=foo). - Defining property file
credentials.propertiesin root classpath containing key/valueAIRTABLE_API_KEY=foo. - On the other hand the API-key could also be added by using the method
Airtable.configure(String apiKey).
See: https://support.airtable.com/hc/en-us/articles/219046777-How-do-I-get-my-API-key-
The API supports environment variable http_proxy. If the variable is set, it is used automatically.
- On Windows:
set http_proxy=http://your_proxy:your_port - On Unix/OS X:
export http_proxy=http://your_proxy:your_port
If endpointUrl contains localhost or 127.0.0.1 proxy settings are ignored automatically.
The Simple Logging Facade for Java SLF4J serves as a simple facade or abstraction for various logging frameworks (e.g. java.util.logging, logback, log4j) allowing the end user to plug in the desired logging framework at deployment time.
The API of Airtable itself is limited to 5 requests per second. If you exceed this rate, you will receive a 429 status code and will need to wait 30 seconds before subsequent requests will succeed.
To use this libraray you will need an Airtable object. Simply create one: Airtable airtable = new Airtable();.
This object needs an API-Key or it won't work properly so airtable.configure(AIRTABLE_API_KEY);.
Now the Airtable object needs to know which base you want to access. This method will return a Base object which will be used in the future:
Base base = airtable.base(AIRTABLE_BASE);
With the Base object you can perform all kind of operations see more at CRUD Operations on Table Records.
The Java implementation of the Airtable API provides automatic object mapping. You can map any table to your own Java classes. But first you need to specify those classes.
The Java objects represent records or 'values' in Airtable. So the class attributes need to be adjusted to the Airtable Base.
In Airtable we got a table 'Actor'. The columns represent the class attributes.
This is how our 'Actor' table looks like:
| Index | Name | Photo | Biography | Filmography |
|---|---|---|---|---|
| 1 | Marlon Brando | Some Photos | Long Text | Reference to the Movie Table |
| 2 | Bill Murray | Some Photos | Long Text | Reference to the Movie Table |
| 3 | Al Pacino | Some Photos | Long Text | Reference to the Movie Table |
| ... | ... | ... | ... | ... |
Now our Java class should look like this:
public class Actor {
private String id;
@SerializedName("Name")
private String name;
@SerializedName("Photo")
private List<Attachment> photo;
@SerializedName("Biography")
private String biography;
@SerializedName("Filmography")
private String[] filmography;
public String getId() {
return id;
}
public void setId(String id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String[] getFilmography() {
return filmography;
}
public void setFilmography(String[] filmography) {
this.filmography = filmography;
}
public List<Attachment> getPhoto() {
return photo;
}
public void setPhoto(List<Attachment> photo) {
this.photo = photo;
}
public String getBiography() {
return biography;
}
public void setBiography(String biography) {
this.biography = biography;
}
}For each column we give the Java class an attribute with the column name (Be careful! See more about naming in the Section Annotations)
and add Getters and Setters for each attribute. The attribute types can be either primitive Java types like String and Float for Text and Numbers,
String Array for references on other Tables or Attachment for attached photos and files.
Now we got everything we need to create our first Airtable table object.
We use the Java class we just wrote to specify what kind of Object should be saved in our table. Then we tell our base-object which table we want to access.
All the records saved in our Airtable Base now should be in our local Table Object.
Example:
Base base = airtable.base('AIRTABLE_API_KEY');
Table<JAVA CLASS> actorTable = base.table("NAME OF THE TABLE", <JAVA_CLASS>);
//Example with the Actor Table
Table<Actor> actorTable = base.table("Actors", Actor.class);The Java implementation of the Airtable-API provides an implementation of basic Airtable objects such as attachments and thumbnails.
Photos and attached files in Airtable are retrieved as Attachments. Photos furthermore contain Thumbnail-Objects for different sizes.
All the Attachment-objects got the following attributes:
- String
id - String
url - String
filename - Float
size - String
type
Photos additionally have:
- Map<String,Thumbnail>
thumbnails
A Thumbnail is generated for image files in Airtable. Thumbnails are bound to an Attachment-object as a key/value Map.
The keys are small and large for the different sizes. The value is a Thumbnail-object.
A Thumbnail-object got the following Attributes:
- String
name - String
url - Float
width - Float
height
Note: The name of a Thumbnail Object is identical with it´s key ( small or large ).
Use the annotation @SerializedName of Gson to annotate column names containing -, empty characters or other not in Java mappable characters.
The airtable.java API will respect these mappings automatically.
import com.google.gson.annotations.SerializedName;
//Column in Airtable is named "First- & Lastname", which is mapped to field "name".
@SerializedName("First- & Lastname")
private String name;With the integrated Sort element you can retrieve a list of sorted objects that specifies how the records will be ordered.
Each sort object must have a field key specifying the name of the field to sort on, and an optional direction key that is either "asc" or "desc".
The default direction is "asc".
For example, to sort records by Name, pass in:
Sort sort = new Sort("Name", Sort.Direction.desc);
List<Movie> listMovies = movieTable.select(sort);If you set the view parameter, the returned records in that view will be sorted by these fields.
Detailed example see TableParameterTest
Select list of items from table:
table(name).select(): get all records of tablenametable(name).select(Integer maxRecords): get maxmaxRecordsrecords of tablenametable(name).select(String[] fields): get records of tablenamewith only the specifiedfieldstable(name).select(String view): get records of tablenamewith the specifiedview(more about views)table(name).select(Sort sortation): get records of tablenameusingsortto sort records (More about Sort here)table(name).select(Query query): get records of tablenameusingqueryto filter
Base base = new Airtable().base("AIRTABLE_BASE");
List<Movie> retval = base.table("Movies", Movie.class).select();Detailed example see TableSelectTest.java
The REST-API of Airtable is limited to return max. 100 records. If the select has more than 100 records in result an offest is added to
returned data. The Airtable.java client will solve this and tries to load the offset data automatically.
Use find to get specific records of table:
table(name).find(String id): get record withidof tablename
Base base = new Airtable().base("AIRTABLE_BASE");
Table<Actor> actorTable = base.table("Actors", Actor.class);
Actor actor = actorTable.find("rec514228ed76ced1");Detailed example see TableFindTest.java
Use destroy to delete a specific records of table:
table(name).destroy(String id): delete record withidof tablename
Base base = airtable.base("AIRTABLE_BASE");
Table<Actor> actorTable = base.table("Actors", Actor.class);
actorTable.destroy("recapJ3Js8AEwt0Bf"); Detailed example see TableDestroyTest.java
First build your record. Then use create to generate a specific records of table:
-
Table<Actor> actorTable = base.table("Actors", Actor.class); Actor newActor = new Actor(); newActor.setName("Neuer Actor");: build your recordActor test = actorTable.create(newActor);: create the recently build record
// detailed Example see TableCreateTest.java
Base base = airtable.base("AIRTABLE_BASE");
Table<Actor> actorTable = base.table("Actors", Actor.class);
Actor newActor = new Actor();
newActor.setName("Neuer Actor");
Actor test = actorTable.create(newActor);Detailed example see TableCreateRecordTest.java
Use update to update a record of table:
-
Actor.setName("New Name");: set or update to a new ValueActor test = actorTable.update(Actor);: update the Actor in the Table
// detailed Example see TableCreateTest.java
Actor marlonBrando = ...;
marlonBrando.setName("Marlon Brando");
Actor updated = actorTable.update(marlonBrando);Detailed example see TableUpdateTest
Short overview of features, which are supported:
-
Airtable Configure
- configuration of
proxy - configure
user/passwordfor proxy - configuration of
AIRTABLE_API_KEY&AIRTABLE_BASE - configuration of
requestTimeout
- configuration of
-
Select Records
- SelectAll
- Queries (
maxRecords,sort&view) - Support of
filterByFormula - Support of
paging - Support of appending
offsetdata
-
Find Record
-
Create Record
-
Update Record
-
Replace Record (could be done by update)
-
Delete/Destroy Record
-
General requirements
- Automatic ObjectMapping
- Read: convert to Objects
- Read: conversion of
Attachments &Thumbnails - Write: convert Objects to JSON
- Automatic ObjectMapping
-
Errorhandling
see: CONTRIBUTING.md
There are JUnit tests and integration tests to verify the API.
For unit testing, the JSON-responses are mocked by WireMock.
The integration tests are based on the Airtable template Movies, which could be created in your own account to run integration tests. Add your configuration of AIRTABLE_API_KEY & AIRTABLE_BASE to the integration tests locally.
- Airtable.js: official JavaScript Client
- Airtable Ruby Client: Ruby Client
- Airtable Python: Python Client
- Airtabler: R interface to the Airtable API
- Airtable.cs: AirTable API .Net client.
- and more Github-Projects using topic Airtable
Thank you very much for these great frameworks and libraries provided open source!
We use following libraries:
MIT License, see LICENSE
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent