Michael V. Colianna's avatar

Fear of APIs

Or why you should not overengineer your writing

July 12, 2018

Or why you should not overengineer your writing

It's been a little while since my last post! I was very busy with my full time job, which actually relates to this post! I make my living as a web developer. This means I work with things called APIs. It's not important whether you know what that means outside of how it pertains to this little story.

I do my writing in Google Docs. Google provides one of those APIs for Docs. Outside of the web interface you see on Google's site, the API lets people get things like file names, lists of files in folders, modification times, and the like. If you have a particular document you've been working on for a while, it will even let you grab specific revisions.

Some of my writing is done at my iMac, but some is done on my Chromebook. My Chromebook is a little slow if I'm opening an entire manuscript. To alleviate that, I split my work up in folders by chapter. Working on 5,000 words at a time is a lot nicer for my Chromebook than 100,000 all at once.

Splitting my work up into folders, by chapter, required me to cobble them all together if someone wanted the entire manuscript. Enter the Google API for Docs.

Being a web developer, I wrote a small script that does the following:

  1. Asks, "Hey there, Google API, can I have a list of files in folder X?"
  2. Receives the list and iterates through it to get the chapters.
  3. For each chapter, asks, "Hey there, Google API, can I have the contents of document Y?"
  4. Receives the contents and appends them into a single document for me.

Instead of cobbling them together by hand, I run my script and in maybe three minutes I've got my full manuscript. Sounds great, right?

Those steps are really simplified. So take a look at step 3 again. When my script asks for the contents of the document, there are actually some sub-steps:

  1. Asks, "Hey there, Google API, can you give me a list of document Y's revisions?"
  2. Receives the list of revisions.
  3. Asks, "Hey there, Google API, can you give me revision A of document Y?"

When I wrote my script, revision A was the most recent by time - the same one I'd see if I were to open the chapter in Docs. As you might be able to guess, that changed and I never noticed. My ask for the revision needed to be more explicit than it was, so step 4 of the first list was the contents from, say, May of 2015. In other words, my script was compiling old documents.

TLDR; As far as I can tell, I've been responding to requests wrong since at least October of 2017.


(Image Source)

Comments

comments powered by Disqus