Build Status Coverage Status Dependency Status Gem Version

Under construction!

Any gem released prior to 1.x may have an unstable API. As the triannon server and this client are in rapid development (as of 2015), expect new gem releases that could break the API.

Triannon Client

A client for the triannon service, see also

Installation into ruby projects

gem 'triannon-client'

Then execute:


Using the client


Edit a .env file to configure the triannon server address etc. (see .env_example); or use a configure block. The configuration for authentication depends on prior triannon server configuration, see

This example configuration may work with a triannon server running on localhost in the development environment (see below for details).

require 'triannon-client'
::TriannonClient.configure do |config|
  config.debug = false = 'http://localhost:3000'
  config.client_id = 'clientA'
  config.client_pass = 'secretA'
  config.container = '/annotations/bar'
  config.container_user = ''
  config.container_workgroups = 'org:wg-A, org:wg-B'

Get a client instance

A new instance is initialized using the configuration parameters (see above).

tc =

Get a list of annotations

# return an RDF::Graph
graph = tc.get_annotations
anno_uris = tc.annotation_uris(graph)
anno_ids = {|uri| tc.annotation_id(uri) }

Get a particular annotation

# the default response is an open annotation in an RDF::Graph
oa_anno = tc.get_annotation(id)

For specific response formats, specify an HTTP Accept header, e.g.

# explicitly request jsonld with an open annotation or a IIIF context
anno_oa   = tc.get_annotation(id, `application/ld+json; profile=""`)
anno_iiif = tc.get_annotation(id, `application/ld+json; profile=""`)
# convenience methods to do the above
anno_oa   = tc.get_oa_annotation(id)
anno_iiif = tc.get_iiif_annotation(id)

Create an annotation


Delete an annotation

uri ="")
id = tc.annotation_id(uri) #=> "45%2F4a%2Fc0%2F93%2F454ac093-b37d-4580-bebd-449f8dabddc9"

Note: the annotation URI contains a pair-tree path (created by a Fedora 4 repository for triannon annotations). The annotation ID is the entire pair-tree path, after a URI escape. The URI escape makes it easier to work with the ID for tc.get_annotation(id) and tc.delete_annotation(id). For more information on object storage using pair-trees, see


Clone and install:

git clone
cd triannon-client
./bin/  # runs bundle install

Run tests:


The server request/response cycle has been recorded in spec/fixtures/vcr_cassettes (see

Tests with live server interactions

git clone
git clone triannon_reset
cp ./triannon_reset/ triannon/bin/
cd triannon
  • Run the triannon client specs against the localhost server. sh git clone cd triannon-client ./bin/ # bundle update and package rm -rf spec/fixtures/vcr_cassettes rake