pocketapi v0.1

0

Monthly downloads

0th

Percentile

Wrapper Around the 'Pocket' API

Functions that interface with the 'Pocket' API (<https://getpocket.com/developer/>). Allows the user to get, add, and modify items in their own 'Pocket' account.

Readme

pocketapi

R build status Codecov test coverage CRAN status Lifecycle: experimental

This is a R wrapper for the Pocket API. You can use pocketapi to access and modify your own pockets and to add new links to your Pocket programmatically.

Functions include:

  • pocket_add()
  • pocket_get()
  • pocket_archive()
  • pocket_delete()
  • pocket_favorite()
  • pocket_unfavorite()
  • pocket_tag()

Installation

CRAN Version

The package is not yet on CRAN.

Current Development Version

This package is currently only available on GitHub. You can install it using devtools.

# install devtools package if it's not already
install.packages("devtools")

# install package from GitHub
devtools::install_github("correlaid/pocketapi")

# load package
library(pocketapi)

Get Started

Authentication

Create a Pocket Application

You need to create a Pocket application in the Pocket developer portal to access your Pocket data. Don't worry: this app will only be visible to you and only serves the purpose of acquiring the credentials for pocketapi.

  1. Log in to your Pocket account and go to https://getpocket.com/developer/apps/new.
  2. Click "Create New Application". You'll be presented with a form. Choose a sensible application name and a description.
  3. Give your app permissions: Depending on the permissions of your app, you'll be able to use all or a subset of the pocketapi functions:
pocketapi function what it does needed permission
pocket_get get data frame of all your pockets Retrieve
all other pocket_* functions add new Pocket entries Modify
  1. Check any platform for your app - this does not really matter but you need to check at least one box.
  2. Accept the terms of service and click "Create Application".

Get consumer key and token

pocketapi uses the OAuth2 flow provided by the Pocket Authentication API to get an access token for your App. Because Pocket does not closely follow the OAuth standard, we could not provide as smooth an experience as other packages do (e.g. googlesheets4). Instead, the user has to do the following once to obtain an access token:

  1. Request a request token.

    request_token <- get_request_token(consumer_key)
    
  2. Authorize your app by entering the URL created by create_authorize_url in your browser:

create_authorize_url(request_token)

:warning: This step is critical: Even if you have authorized your app before and you want to get a new access token, you need to do the authorization in your browser again. Otherwise, the request token will not be authorized to generate an access token!

  1. Get access token using the now authorized request token
access_token <- get_access_token(consumer_key, request_token)

You can now already use the package by specifying the consumer key and access token manually as arguments to each function call:

pocketapi::pocket_get(consumer_key = consumer_key, access_token = access_token)

To make it easier to work with the package, you should set them as environment variables.

Add the consumer key and access token to your environment

Important: Never make your consumer_key and access_token publicly available - anyone will be able to access your Pockets!

It is common practice to set API keys in your R environment file so that every time you start R the key is loaded.

All pocketapi functions access your consumer_key and access_token automatically by executing Sys.getenv("POCKET_CONSUMER_KEY") respectively Sys.getenv("POCKET_ACCESS_TOKEN") . Alternatively, you can provide an explicit definition of your consumer_key and access_token with each function call.

In order to add your key to your environment file, you can use the function edit_r_environ from the usethis package:

usethis::edit_r_environ()

This will open your .Renviron file in the RStudio editor. Now, you can add the following lines to it:

POCKET_CONSUMER_KEY="yourkeygoeshere"
POCKET_ACCESS_TOKEN="youraccesstokengoeshere"

Save the file and restart R for the changes to take effect.

If your .Renviron lives at a non-conventional place, you can also edit it manually using RStudio or your favorite text editor.

If you don't want to clutter the .Renviron file in your home folder, you can also use a local .Renviron file in your project folder and read it in using the readRenviron() function. In this case, make sure to never share your local .Renviron file.

Get, modify, and add Pockets

Check out the vignette to see in more detail how to add, get, and modify your Pockets using those functions.

library(pocketapi)
vignette("pocketapi")

Limitations

This package has some limitations:

  • You can only modify your own Pockets.
  • The Pocket API does not follow REST API standards and exhibits some weird behaviours. For example, even if a modify action is not successful, the API will still return "success". See [issue #26 for a discussion of weird behaviours of the API.

Contribute

Contributions to this package are welcome. Please see CONTRIBUTING.md.

Functions in pocketapi

Name Description
create_authorize_url create_authorize_url
pocket_post_ pocket_post_
pocket_modify_bulk_ pocket_modify_bulk_
pocket_add pocket_add
pocket_archive pocket_archive
pocket_modify pocket_modify
pocket_get pocket_get
warn_for_failures_ warn_for_failures_
pocket_favorite pocket_favorite
pocket_delete pocket_delete
pocket_tag pocket_tag
pocket_unfavorite pocket_unfavorite
gen_add_action_ gen_add_action_
gen_tag_action_ gen_tag_action_
get_access_token get_access_token
get_request_token get_request_token
parse_item_ parse_item_
%>% Pipe operator
extract_action_results_ extract_action_results_
gen_action_ gen_action_
check_for_add_success_ check_for_add_success_
No Results!

Vignettes of pocketapi

Name
pocketapi.Rmd
No Results!

Last month downloads

Details

License MIT + file LICENSE
Encoding UTF-8
LazyData true
BugReports https://github.com/CorrelAid/pocketapi//issues
URL https://github.com/CorrelAid/pocketapi/
RoxygenNote 7.1.1
VignetteBuilder knitr
NeedsCompilation no
Packaged 2020-11-19 08:30:07 UTC; yannik
Repository CRAN
Date/Publication 2020-11-20 10:20:02 UTC

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/pocketapi)](http://www.rdocumentation.org/packages/pocketapi)