The Weekly Review

by Chris Bowler

Using the ESV API

I mentioned last week that my Bible study set up using Ulysses was published over at The Sweet Setup earlier this month. This resulted in a handful of people asking about my reference to using the ESV API to populate Ulysses with Scripture.

I was (obviously) not quite clear in the article. It was my intention to start that a person could use the API. But I have not been doing that myself. Instead, I manually copy and paste 10 chapters at a time from the Bible Study app into Ulysses when needed. I do this for a couple reasons:

  • It’s easier to focus on my notes and highlights this way. I would have to go through the entire app to get my content out anyway (Olive Tree, like so many other companies, has not made it easy to get your data out), so I might as well include this in the migration process
  • Whether you copy and paste manually or use the API, there’s going to be some massaging of the content required

But since there were a few people curious about this, there may be some value in walking through how one could use the API.

Get a client

First, a disclaimer. I am no developer so there will likely be better ways to go about this. But I am technical enough to get content via an API 😀

The first step is to decide how you’re going to interact with the API. You can certainly make cURL requests from the command line … but that’s pretty neck beardy. When I have to work with an API, I prefer to use a graphical client. A coworker recommended Postman multiple times and it’s the best option I’m aware of.

Setting things up

Once you have that, you can head over to the ESV site and create yourself an account. From there, you need to create an “app” so you can get an access token to use in your API calls.
This needs to be included in the headers of each call, so no, you can’t skip it.

From there, you can head to the ESV API docs to figure out how to build your requests. There are a lot of options available, but for this purpose, you want a very minimal return to your response. Just the text and verses. You can set build your desired query right on their API page (click in the text boxes, then use the “Try It Out” button at the bottom.

It can take some twiddling and tweaking to get this just the way you want, but here’s a sample query of how I would use it:

https://api.esv.org/v3/passage/text/?q=ps1-10&include-passage-references=false&include-verse-numbers=true&include-footnotes=false&include-footnote-body=false&include-short-copyright=false&include-copyright=false&include-passage-horizontal-lines=false&include-heading-horizontal-lines=false&include-headings=true&include-selahs=true&indent-paragraphs=0&indent-poetry=false&indent-declares=0&indent-psalm-doxology=0&line-length=50

This is where Postman makes things pretty easy. You can simply copy and paste this URL into the GET request field at the top of the app.

Be sure to also include your authorization token in the Headers tab. It took me a bit to figure out how the ESV API wanted this to be formatted, but do not use the default options Postman provides. I set their authentication Type to No Authentication, then manually entered in the correct values in the headers.

Clean up

Once you have tested this a few times and you get the content that you want, you can run a query and then copy & paste the results into Ulysses. And this is where some clean up will be required.

If you have development chops, you could probably script up some solution for formatting the text as you want it (Regex, anyone?). The API does things like add square brackets to each verse number, so Ulysses treats them as links (see above). So it can take some time to get the content as you personally prefer it.

But at the very least, you can get what you need from the API. I hope that helps anyone who was considering this option!

&

Don't Make Me Think

Medium’s claps and Basecamp’s boosts. These are two items that feel like the creators have gone and ignored Steve Krug’s advice from his excellent book. Both features went from a very straightforward use case to one that caused me to pause and ponder.

I talked a little about Medium’s change from hearts to claps last summer (Vol IV Issue 23 to be exact), so I’ll focus on Basecamp this time.

In its latest version, Basecamp 3, there was an option to clap for someone’s post. Like Twitter or Facebook, these claps are clearly applause, but the true purpose of giving a clap can be ambiguous. All of the following are applicable:

  • I might clap to acknowledge a thought — like I’m saying, “Hey, I read this”
  • I could clap to show support for someone who had less than ideal news
  • And, of course, I may clap because I thought someone’s work or thinking was really good (truly, applause)

Recently, the Basecamp team changed this feature so that applause is now Boosts. When giving a Boost, you can use any emoji available as well as add up to 16 characters of text. I understand some of the sentiment and thinking of the Basecamp team. But I do feel like the added complexity is not worth the benefit you get from the change.

A good example of where this applies is a weekly automatic check-in we use at Wildbit. We have a Work from Home team where we talk about remote working. One of the practices the team has grown to love most is our weekly check-in asking “How was your weekend?” This is where we get to know our teammates better and to learn about our families. In a company where we call each other a family, we all welcome these glimpses into each other's lives.

This is where the old model of simple claps could fall short. When someone shared that they were sick and stayed in bed all weekend, or when their spouses grandfather had a stroke, a clap doesn’t quite feel appropriate.

But (and it’s a big but) in that scenario, you could leave a comment. “Get better soon” or “I hope your grandpa recovers fully” are easy to communicate using one of Basecamp’s main features. The combination of claps and comments gave you the tools you needed to quickly and easily express your thoughts to the team.

Boosts were intended to fill that gap, but I (and many on our team) have found ourselves sitting and wondering which emoji makes the most sense. And 16 characters isn’t enough to communicate your full thoughts, so you still turn to comments in these kinds of situations.

And the worst aspect is that Boosts have caused some people to stop giving “applause”. Some would give a clap for all answers to “How was your weekend?” to indicate their enjoyment of seeing everyone’s updates. Now, they’re not sure of the best response and, in the face of too many choices, they make none at all.

Claps were a very straightforward, easy to understand option that was easy to use. Boosts add friction. Enough so that the having to stop and think has caused the opposite effect that the Basecamp team was hoping for. Sometimes, design decisions that seem clever add complexity.

And no one needs that in their tools.

&