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
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
https://twitter.com/BenjaminWolfe/status/1508160932660322308
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…
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.
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…
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/…
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.)
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/…
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.
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).
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.
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.
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.
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.
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/…
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. 😉🧵
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!
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!
https://twitter.com/nic_crane/status/1088392126667390976?t=QU-MRNXs6d4FdxO01SYB1A&s=19
• • •
Missing some Tweet in this thread? You can try to
force a refresh
