Thread by @BenjaminWolfe

A quick tweetorial on using #RStats to hit an API!

I used the {httr} & {jsonlite} pkgs to migrate 789 journal entries from my old platform to Notion. It's a great case study. I'm going to show you my building blocks. 🧱

You can use what I learned for any API project!

1/n

2/

First, I went to the "Getting Started" page of the Notion API docs. Makes sense, since I was getting started.

It told me crucial details like how to create an integration, give it permissions on a Notion DB, and get the DB ID.

developers.notion.com/docs/getting-s…

3/

But before long I was awash in code examples that were either in node.js or curl, and to be frank I wasn't sure how to work with them.

I know, I should, but hey, this is a tutorial for people like me who… didn't really know how to do it easily.

4/

It ended up being very easy—almost trivial—once I got a few things down. Let's work through an example.

This is the docs page for "creating a page in Notion." I'll take it section by section. By the end we'll have fully working #RStats code.

developers.notion.com/reference/post…

5/

To start w/, at the right are API examples. Always start w/ the examples, right?

Notice they give 2 options: JS and Shell. Go w/ Shell.

I've copied the text of that example into a gist for convenience:

gist.github.com/BenjaminWolfe/…

6/

First thing to note is all the backslashes. They just mean "continue on to the next line." You can ignore them when you're translating this into #RStats code.

(This tutorial will be quite basic for some, just right for others! Feel free to skim.)

7/

I also made a gist of the #RStats translation of our shell code example.

Notice anything familiar? In the shell code, 3 lines are marked -H for "header." To make those headers in httr, create a *named vector*. The example should be ~easy to follow.

gist.github.com/BenjaminWolfe/…

8/

Next let's look at out the "data" part of the curl code.

This part of the example is in #JSON. If you don't know JSON well, it's easy to get the hang of. Check out the well written specs at json.org.

Quick summary of the important bits in the next tweet.

9/

JSON is mostly dictionaries of key-value pairs. Keys & values are separated by a colon. Dictionaries are wrapped in curly braces.

{"emoji": "🥬"}

The "value" can itself be a dictionary!

Square brackets mean a list of nameless values (which can each be a dictionary).

10/

Construct that same example in #RStats, we use a lot of lists.

Dictionaries of key-value pairs are *named lists* in R.

list(emoji = "🥬")

Anywhere you see square brackets in your API, use an *unnamed list*.

Here "title" is an unnamed list of length 1 of named lists.

11/

You do need to *actually* turn that #RStats list into a #JSON string to make your API call, though.

To do that, use toJSON, from the {jsonlite} pkg.

The only trick I've found is to use auto_unbox = TRUE; otherwise there are some defaults that mess with your API format.

12/

Next, notice that I use the {httr} function POST.

There are different types of API request, like GET, PUT, and POST. You'll know which from the API docs. Each has an analogue in {httr}.

The URL is called the API endpoint. You'll also get that from the API docs.

13/

Usually your API will return something! Here we're just making Notion pages, but there's still a response, and I wanted to keep it for reference & troubleshooting.

To extract that content it's helpful to use {httr}'s content() function. Pretty clear name, huh.

14/

That's all there is to know! Here's the gist for the whole script I wrote to migrate my journal.

I wrote little functions to create parts of the API request body, and a function to put it all together.

Then I wrote one badass pipe to do everything!

gist.github.com/BenjaminWolfe/…

15/15

Special thanks to @jeremy_data and @thomas_mock for the encouragement to use a simple gist and tweet thread rather than a blog post.

It turned out to be just as involved as a blog post anyway! Just easier to write. 😉🧵

16/15

And thanks to memories of tweets like this one, I'm curious how you pronounced {httr} in your head as you read that!

I always spelled out h-t-t-r till Nicola suggested otherwise!