/ 
Hypothesis-API-0.13
River stage zero No dependents
/ Hypothesis::API

NAME

Hypothesis::API - Wrapper for the hypothes.is web (HTTP) API.

VERSION

Version 0.13

SYNOPSIS

A Perl wrapper and utility functions for the hypothes.is web (HTTP) API.

Create a hypothes.is object.

use Hypothesis::API;

my $H = Hypothesis::API->new();

# or if user-specific actions without login are needed (no known uses yet):
my $H = Hypothesis::API->new($username);

# or if login is needed (usually for annotator-store alterations)
my $H = Hypothesis::API->new($username, $password);

Login-required functionality:

$H->login; 

my $payload = {
    "uri"  => 'http://my.favorite.edu/doc.html',
    "text" => "testing create in hypothes.is API"
};
my $id = $H->create($payload);
$H->delete_id($id);

Search functionality (no login needed):

my $annotation = $H->read_id($id);
die if ($annotation->{'id'} ne $id);

my $page_size = 20;
my $iter = $H->search({limit => 100}, $page_size);
my @annotations;
while ( my $item = $iter->() ) {
    push @annotations, $item;
}

my $total = $H->search_total({limit => 100}, $page_size);
print "Reported $total total items.\n";

EXPORT

Currently nothing.

SUBROUTINES/METHODS

create(\%payload)

Generalized interface to POST /api/annotations

In the simplest form, creates an annotation $payload->{'text'} at $payload->{'uri'}. For more sophisticated usage please see the hypothes.is API documentation.

Returns annotation id if created or HTTP status code otherwise.

delete_id($id)

Interface to DELETE /api/annotations/<id>

Given an annotation id, returns a boolean value indicating whether or not the annotation for that id has been successfully delete (1 = yes, 0 = no).

login

Proceeds to login; on success retrieves and stores CSRF and bearer tokens.

read_id($id)

Interface to GET /api/annotations/<id>

Returns the annotation for a given annotation id if id is defined or nonempty. Otherwise (in an effort to remain well-typed) returns the first annotation on the list returned from hypothes.is. At the time of this writing, this functionality of empty 'search' and 'read' requests are identical in the HTTP API, but in this Perl API, 'read' returns a scalar value and 'search' returns an array.

search(\%query, $page_size)

Generalized interface to GET /api/search

Generalized query function.

query is a hash ref with the following optional keys as defined in the hypothes.is HTTP API: * limit * offset * uri * uri.parts * text * quote * user

page_size is an additional parameter related to $query->limit and $query->offset, which specifies the number of annotations to fetch at a time, but does not override the spirit of either of the $query parameters.

Tries not to return annotations created after initiation of the search.

Note that while this function has been made robust to addition of new annotations being created during a query, it is not yet robust to deletion of annotations.

search_total(\%query, $page_size)

Specific interface to GET /api/search that simply returns the total number of query results. See the search subroutine for more details on parameters.

update_id($id, \%payload)

Interface to PUT /api/annotations/<id>

Updates the annotation for a given annotation id if id is defined and the user is authenticated and has update permissions. Takes a payload as described for 'search'. Only fields specified in the new payload are altered; other existing fields should remain unchanged.

Returns a boolean value indicating whether or not the annotation for that id has been successfully updated (1 = yes, 0 = no).

EXTERNAL ACCESSORS

get_ua_timeout($timeout)

Gets the timeout (in seconds) of the internal LWP::UserAgent object used to make requests to the Hypothes.is service.

set_ua_timeout($timeout)

Under certain circumstances, particularly for testing, it is helpful to set the timeout (in seconds) used by LWP::UserAgent to make requests to the Hypothes.is service.

AUTHOR

Brandon E. Barker, <brandon.barker at cornell.edu>

Created 06/2015

Licensed under the Apache License, Version 2.0 (the "Apache License"); also licensed under the Artistic License 2.0 (the "Artistic License"). you may not use this file except in compliance with one of these two licenses. You may obtain a copy of the Apache License at

http://www.apache.org/licenses/LICENSE-2.0

Alternatively a copy of the Apache License should be available in the LICENSE-2.0.txt file found in this source code repository.

You may obtain a copy of the Artistic License at

http://www.perlfoundation.org/artistic_license_2_0

Alternatively a copy of the Artistic License should be available in the artistic-2_0.txt file found in this source code repository.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License or Artistic License for the specific language governing permissions and limitations under the licenses.

BUGS

Please report any bugs or feature requests at https://github.com/bbarker/Hypothesis-API/issues. Alternatively, you may send them to bug-hypothesis-api at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Hypothesis-API, but this is not preferred. In either case, I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

REPOSITORY

https://github.com/bbarker/Hypothesis-API

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Hypothesis::API

You can also look for information at:

ACKNOWLEDGEMENTS

We are thankful for support from the Alfred P. Sloan Foundation.