Hypothesis::API - Wrapper for the hypothes.is web (HTTP) API.
Version 0.13
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";
Currently nothing.
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.
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).
Proceeds to login; on success retrieves and stores CSRF and bearer tokens.
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.
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.
Specific interface to GET /api/search that simply returns the total number of query results. See the search subroutine for more details on parameters.
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).
Gets the timeout (in seconds) of the internal LWP::UserAgent object used to make requests to the Hypothes.is service.
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.
Brandon E. Barker, <brandon.barker at cornell.edu>
<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.
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.
bug-hypothesis-api at rt.cpan.org
https://github.com/bbarker/Hypothesis-API
You can find documentation for this module with the perldoc command.
perldoc Hypothesis::API
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Hypothesis-API
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Hypothesis-API
CPAN Ratings
http://cpanratings.perl.org/d/Hypothesis-API
Search CPAN
http://search.cpan.org/dist/Hypothesis-API/
We are thankful for support from the Alfred P. Sloan Foundation.
To install Hypothesis::API, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Hypothesis::API
CPAN shell
perl -MCPAN -e shell install Hypothesis::API
For more information on module installation, please visit the detailed CPAN module installation guide.