Benjamin Wolfe Profile picture
Mar 30, 2022 16 tweets 9 min read Read on X
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. A basic example in the docs...
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… Top of the API docs page, l...
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/… Just some of the text of my...
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.) First few lines of the gist...
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/… A named vector of headers, ...
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. The first few lines of the ...
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). Same code sample from the p...
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. Image
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. A few lines from the gist a...
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. Same R code. Here we highli...Review of the original page...
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. Same R code again. Here we ...
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!

• • •

Missing some Tweet in this thread? You can try to force a refresh
 

Keep Current with Benjamin Wolfe

Benjamin Wolfe Profile picture

Stay in touch and get notified when new unrolls are available from this author!

Read all threads

This Thread may be Removed Anytime!

PDF

Twitter may remove this content at anytime! Save it as PDF for later use!

Try unrolling a thread yourself!

how to unroll video
  1. Follow @ThreadReaderApp to mention us!

  2. From a Twitter thread mention us with a keyword "unroll"
@threadreaderapp unroll

Practice here first or read more on our help page!

Did Thread Reader help you today?

Support us! We are indie developers!


This site is made by just two indie developers on a laptop doing marketing, support and development! Read more about the story.

Become a Premium Member ($3/month or $30/year) and get exclusive features!

Become Premium

Don't want to be a Premium member but still want to support us?

Make a small donation by buying us coffee ($5) or help with server cost ($10)

Donate via Paypal

Or Donate anonymously using crypto!

Ethereum

0xfe58350B80634f60Fa6Dc149a72b4DFbc17D341E copy

Bitcoin

3ATGMxNzCUFzxpMCHL5sWSt4DVtS8UqXpi copy

Thank you for your support!

Follow Us!

:(