During the last CFSummit (2021) I did a talk on leveraging Airtable’s API using the BaseQL plugin to perform CRUD operations using GraphQL. You can find the talk here: All Videos – ColdFusion (adobe.com)

Except, as a couple folks pointed out, I actually just showed how to do R operations, no C U or D, as my time was a bit short. I’d figured extrapolating from my talk would be fairly trivial. As it turns out… not so much, there’s a fairly big different between the query and the mutation ops in GraphQL, so the other night I did the talk again and added an insert operation page, and I thought I would detail what that takes here. For the general setup of Airtable, BaseQL and doing reads, please hop over to the video section and give that vid a watch.

So as mentioned, there’s quite a difference in GraphQL between reads (query) and writes/deletes/updates (mutations). They use a slightly different syntax, and this alters the way you have to write your code to hit the BaseQL endpoint when updating your Airtable datasource (or, I’m assuming, any GraphQL endpoint).

Let’s start off by looking at the GraphQL for a simple data return.

If we were to, say, want to get the “done”, “id”, “item” and “note” fields back from the airtable named “table1”, our GraphQL would look like this:

query MyQuery {
   table1 {
      done
      id
      item
      notes
   }
}

Fairly easy, and an excellent example of GraphQL’s “make your query look like your return” methodology. And, just as a reminder, since we have to format the GraphQL query as JSON when sending it using CFHTTP, the modified version of the above query would look like this:

Again, pretty simple, we just converted the GraphQL formatting to JSON (and removed the query name as it is not needed in this case).

But what about a write? Or, in GraphQL parlance, a “mutation”? The GraphQL for inserting a new row would look something like this:

mutation MyMutation {
      insert_table1(done: false, item: "Something", notes: "Some notes") {
      id
   }
}

A couple notes here. First, in the “insert” portion of the mutation, you’ll see there’s no “id” listed. That’s because Airtable autogenerates a unique ID for each row. You’ll also see another section later that does have an ID. That will return an ID in JSON from the endpoint for the new row. All mutations MUST return some kind of data, the usual return is the ID you just made but you can return everything if you’d like.

OK so if you’re like me, you would then extrapolate that to do a mutation using CFHTTP you’d write something like:

{"mutation": "{insert_table1 (done: false, item: \"Something\", notes: \"Some notes\"){

id

}}"}

And, like I was, you’d be wrong. It took me entirely too long to discover (the docs for this are… somewhat lacking) that the proper string formatting would actually look like:

{"query": "mutation {insert_table1(done: false, item: \"Something\", notes:  \"Some notes\") {id}}"}

What the heck? Right, so basically it seems as though the endpoint is still expecting a query, which normally defaults to read. But if you pass “mutation” in and add the “insert_” before your table name, it will identify it as an insert and process it thusly. Fun!

So there you go. I’ll be back next week with an update script and maybe a delete as a bonus!