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.