How to use Hypothesis API from R?

Introduction

This vignette provides an overview and usage examples of the {hypothesis} R package, which is a wrapper for the Hypothesis API. The package allows you to interact with the Hypothesis annotation platform programmatically.

Authentication

Before using the {hypothesis} package, you need to obtain an API key from the Hypothesis platform. You can generate an API key by following the instructions:

Visit the Hypothesis website at https://hypothes.is/ or self-hosted instance.
Sign in to your account or create a new account if you don’t have one.
Once you are signed in, click on your account avatar in the top right corner of the page and select “Account details” from the dropdown menu.
In the account settings page, click on the “Developer” tab.
Click Generete your API token

To set your API key as an environment variable, you can use the Sys.setenv() function:

Sys.setenv(HYPOTHESIS_API_KEY = "your_api_key")

or set the it in the .Renviron file. e.g. usethis::edit_r_environ()

Usage

By default the package is using https://hypothes.is/api/, you can modify the host to point to custom Hypothesis instance by specify HYPOTHESIS_API_PATH environment variable.

Sys.setenv(HYPOTHESIS_API_PATH = "https://hypothesis.company.com/api/")

The {hypothesis} package provides several functions for interacting with the Hypothesis API. Here, we will demonstrate the usage of some key functions:

search_annotations()

This function allows you to search for annotations based on various criteria. Here’s an example of how to use it:

library(hypothesis)

# Search for annotations with the keyword "R programming"
# Check default parameters in function docs
results <- search_annotations(any = "R programming")

# Print the first 10 annotations
head(results, 10)

The annotation() function allows you to perform actions on individual annotations. Here are some examples:

# To interact with annotation you need to specify correct annotation id. 
# Fetch annotation details
annotation_details <- annotation("annotation_id")

# Update an annotation's text
updated_annotation <- annotation("annotation_id", action = "update", text = "Updated text")

# Flag an annotation
flagged_annotation <- annotation("annotation_id", action = "flag")

The get_groups() function retrieves a list of groups from the Hypothesis platform. Here’s an example:

# Retrieve all groups
groups <- get_groups(authority = "localhost")

The group() function allows you to fetch group details or update group information. Here are some examples:

# Fetch group details
group_details <- group("group_id")

# Update group information
updated_group <- group("group_id", action = "update", name = "Updated Group Name")

The get_profile() function fetches the profile information of the currently-authenticated user. Here’s an example:

# Fetch profile information
profile <- get_profile()

# Print the user's display name
cat("Display Name:", profile$user_info$display_name, "\n")

Conclusion

This vignette provided an introduction to the hypothesis R package and demonstrated its usage with the Hypothesis API. You can explore the package further by referring to the package documentation and the official Hypothesis API documentation.