Struct hypothesis::Hypothesis

pub struct Hypothesis {
    pub username: String,
    pub user: UserAccountID,
    // some fields omitted
}

Hypothesis API client

Fields

username: String

Authenticated user

user: UserAccountID

“acct:{username}@hypothes.is”

Implementations

impl Hypothesis

pub fn new(username: &str, developer_key: &str) -> Result<Self, HypothesisError>

Make a new Hypothesis client with your username and developer key (see here on how to get one)

Example

use hypothesis::Hypothesis;
let api = Hypothesis::new(&username, &developer_key)?;

pub fn from_env() -> Result<Self, HypothesisError>

Make a new Hypothesis client from environment variables. Username from $HYPOTHESIS_NAME, Developer key from $HYPOTHESIS_KEY (see here on how to get one)

Example

use hypothesis::Hypothesis;
let api = Hypothesis::from_env()?;

pub async fn create_annotation(
    &self,
    annotation: &InputAnnotation
) -> Result<Annotation, HypothesisError>

Create a new annotation

Posts a new annotation object to Hypothesis. Returns an Annotation as output. See InputAnnotation for examples on what you can add to an annotation.

Example

use hypothesis::Hypothesis;
use hypothesis::annotations::InputAnnotation;

let api = Hypothesis::new(&username, &developer_key)?;
let annotation = api.create_annotation(&InputAnnotation::builder()
                    .text("string")
                    .uri("http://example.com")
                    .group(&group_id)
                    .build()?).await?;
assert_eq!(&annotation.text, "string");

pub async fn create_annotations(
    &self,
    annotations: &[InputAnnotation]
) -> Result<Vec<Annotation>, HypothesisError>

Create many new annotations

Posts multiple new annotation objects asynchronously to Hypothesis. Returns Annotations as output. See InputAnnotation’s docs for examples on what you can add to an annotation.

Example

let api = Hypothesis::new(&username, &developer_key)?;
let input_annotations = vec![
    InputAnnotation::builder()
        .text("first")
        .uri("http://example.com")
        .group(&group_id)
        .build()?,
    InputAnnotation::builder()
        .text("second")
        .uri("http://example.com")
        .group(&group_id)   
        .build()?
];
let annotations = api.create_annotations(&input_annotations).await?;
assert_eq!(&annotations[0].text, "first");
assert_eq!(&annotations[1].text, "second");

pub async fn update_annotation(
    &self,
    annotation: &Annotation
) -> Result<Annotation, HypothesisError>

Update an existing annotation

Change any field in an existing annotation. Returns the modified Annotation

Example

use hypothesis::Hypothesis;
use hypothesis::annotations::InputAnnotation;
let api = Hypothesis::new(&username, &developer_key)?;
let mut annotation = api.create_annotation(&InputAnnotation::builder()
                  .text("string")
                  .uri("http://example.com")
                  .tags(vec!["tag1".to_string(), "tag2".to_string()])
                  .group(&group_id)
                  .build()?).await?;
annotation.text = String::from("New String");
let updated_annotation = api.update_annotation(&annotation).await?;
assert_eq!(updated_annotation.id, annotation.id);
assert_eq!(&updated_annotation.text, "New String");

pub async fn update_annotations(
    &self,
    annotations: &[Annotation]
) -> Result<Vec<Annotation>, HypothesisError>

Update many annotations at once

pub async fn search_annotations(
    &self,
    query: &SearchQuery
) -> Result<Vec<Annotation>, HypothesisError>

Search for annotations with optional filters

Returns a list of annotations matching the search query. See SearchQuery for more filtering options

This returns a max of 50 annotations at once, use search_annotations_return_all if you expect more

Example

use hypothesis::{Hypothesis, UserAccountID};
use hypothesis::annotations::SearchQuery;
let api = Hypothesis::new(&username, &developer_key)?;
/// Search for your own annotations:
let search_query = SearchQuery::builder().user(&api.user.0).build()?;
let search_results = api.search_annotations(&search_query).await?;

pub async fn search_annotations_return_all(
    &self,
    query: &mut SearchQuery
) -> Result<Vec<Annotation>, HypothesisError>

Retrieve all annotations matching query See SearchQuery for filtering options

pub async fn fetch_annotation(
    &self,
    id: &str
) -> Result<Annotation, HypothesisError>

Fetch annotation by ID

Example

use hypothesis::Hypothesis;
let api = Hypothesis::new(&username, &developer_key)?;
let annotation = api.fetch_annotation(&annotation_id).await?;
assert_eq!(annotation.id, annotation_id);

pub async fn fetch_annotations(
    &self,
    ids: &[String]
) -> Result<Vec<Annotation>, HypothesisError>

Fetch multiple annotations by ID

pub async fn delete_annotation(&self, id: &str) -> Result<bool, HypothesisError>

Delete annotation by ID

Example

use hypothesis::Hypothesis;
let api = Hypothesis::new(&username, &developer_key)?;
let deleted = api.delete_annotation(&annotation_id).await?;
assert!(deleted);
assert!(api.fetch_annotation(&annotation_id).await.is_err());

pub async fn delete_annotations(
    &self,
    ids: &[String]
) -> Result<Vec<bool>, HypothesisError>

Delete multiple annotations by ID

pub async fn flag_annotation(&self, id: &str) -> Result<(), HypothesisError>

Flag an annotation

Flag an annotation for review (moderation). The moderator of the group containing the annotation will be notified of the flag and can decide whether or not to hide the annotation. Note that flags persist and cannot be removed once they are set.

pub async fn hide_annotation(&self, id: &str) -> Result<(), HypothesisError>

Hide an annotation

Hide an annotation. The authenticated user needs to have the moderate permission for the group that contains the annotation — this permission is granted to the user who created the group.

pub async fn show_annotation(&self, id: &str) -> Result<(), HypothesisError>

Show an annotation

Show/“un-hide” an annotation. The authenticated user needs to have the moderate permission for the group that contains the annotation—this permission is granted to the user who created the group.

pub async fn get_groups(
    &self,
    query: &GroupFilters
) -> Result<Vec<Group>, HypothesisError>

Retrieve a list of applicable Groups, filtered by authority and target document (document_uri). Also retrieve user’s private Groups.

Example

use hypothesis::Hypothesis;
use hypothesis::groups::GroupFilters;

let api = Hypothesis::new(&username, &developer_key)?;
/// Get all Groups belonging to user
let groups = api.get_groups(&GroupFilters::default()).await?;

pub async fn create_group(
    &self,
    name: &str,
    description: Option<&str>
) -> Result<Group, HypothesisError>

Create a new, private group for the currently-authenticated user.

Example

use hypothesis::Hypothesis;

let api = Hypothesis::new(&username, &developer_key)?;
let group = api.create_group("my_group", Some("a test group")).await?;

pub async fn create_groups(
    &self,
    names: &[String],
    descriptions: &[Option<String>]
) -> Result<Vec<Group>, HypothesisError>

Create multiple groups

pub async fn fetch_group(
    &self,
    id: &str,
    expand: Vec<Expand>
) -> Result<Group, HypothesisError>

Fetch a single Group resource.

Example

use hypothesis::Hypothesis;
use hypothesis::groups::Expand;

let api = Hypothesis::new(&username, &developer_key)?;
/// Expands organization into a struct
let group = api.fetch_group(&group_id, vec![Expand::Organization]).await?;

pub async fn fetch_groups(
    &self,
    ids: &[String],
    expands: Vec<Vec<Expand>>
) -> Result<Vec<Group>, HypothesisError>

Fetch multiple groups by ID

pub async fn update_group(
    &self,
    id: &str,
    name: Option<&str>,
    description: Option<&str>
) -> Result<Group, HypothesisError>

Update a Group resource.

Example

use hypothesis::Hypothesis;

let api = Hypothesis::new(&username, &developer_key)?;
let group = api.update_group(&group_id, Some("new_group_name"), None).await?;
assert_eq!(&group.name, "new_group_name");
assert_eq!(group.id, group_id);

pub async fn update_groups(
    &self,
    ids: &[String],
    names: &[Option<String>],
    descriptions: &[Option<String>]
) -> Result<Vec<Group>, HypothesisError>

Update multiple groups

pub async fn get_group_members(
    &self,
    id: &str
) -> Result<Vec<Member>, HypothesisError>

Fetch a list of all members (users) in a group. Returned user resource only contains public-facing user data. Authenticated user must have read access to the group. Does not require authentication for reading members of public groups. Returned members are unsorted.

Example

use hypothesis::Hypothesis;

let api = Hypothesis::new(&username, &developer_key)?;
let members = api.get_group_members(&group_id).await?;

pub async fn leave_group(&self, id: &str) -> Result<(), HypothesisError>

Remove yourself from a group.

pub async fn fetch_user_profile(&self) -> Result<UserProfile, HypothesisError>

Fetch profile information for the currently-authenticated user.

Example

use hypothesis::Hypothesis;
let api = Hypothesis::new(&username, &developer_key)?;
let profile = api.fetch_user_profile().await?;
assert!(profile.userid.is_some());
assert_eq!(profile.userid.unwrap(), api.user);

pub async fn fetch_user_groups(&self) -> Result<Vec<Group>, HypothesisError>

Fetch the groups for which the currently-authenticated user is a member.

Example

use hypothesis::Hypothesis;
let api = Hypothesis::new(&username, &developer_key)?;
let groups = api.fetch_user_groups().await?;