EZID Client

EZID API Version 2 bindings. See http://ezid.cdlib.org/doc/apidoc.html.

Installation

Add this line to your application's Gemfile:

gem 'ezid-client'

And then execute:

$ bundle

Or install it yourself as:

$ gem install ezid-client

Basic Resource-oriented Usage (CRUD)

See the test suite for more examples.

Create (Mint/Create)

Mint an identifier on a shoulder

Added in v1.4.0: Ezid::Identifier.mint class method.

>> identifier = Ezid::Identifier.mint("ark:/99999/fk4")
I, [2016-03-01T22:20:08.505323 #35148]  INFO -- : EZID MintIdentifier -- success: ark:/99999/fk4tq65d6k
=> #<Ezid::Identifier id=ark:/99999/fk4tq65d6k>

>> identifier.status
I, [2016-03-01T22:20:22.323650 #35148]  INFO -- : EZID GetIdentifierMetadata -- success: ark:/99999/fk4tq65d6k
=> "public"

>> identifier.target
=> "http://ezid.cdlib.org/id/ark:/99999/fk4tq65d6k"

A default shoulder can be configured:

• By environment variable (added in v0.9.1):

export EZID_DEFAULT_SHOULDER="ark:/99999/fk4"

• By client configuration:

Ezid::Client.configure do |config|
  config.default_shoulder = "ark:/99999/fk4"
end

New identifiers will then be minted on the default shoulder when a shoulder is not specified:

>> identifier = Ezid::Identifier.mint
I, [2014-12-09T11:22:34.499860 #32279]  INFO -- : EZID MintIdentifier -- success: ark:/99999/fk43f4wd4v
=> #<Ezid::Identifier id="ark:/99999/fk43f4wd4v">

Create a specific identifier

Changed in v1.4.0: Ezid::Identifier.create now expects the first argument to be the identifier (String) to create; the second optional argument is a hash of metadata elements. Passing the identifier in an :id hash option is deprecated and will be removed in v2.0. The :shoulder hash option is likewise deprecated; use Ezid::Identifier.mint(shoulder, metadata) instead.

>> identifier = Ezid::Identifier.create("ark:/99999/fk4rx9d523/12345")
I, [2014-12-09T11:21:42.077297 #32279]  INFO -- : EZID CreateIdentifier -- success: ark:/99999/fk4rx9d523/12345
=> #<Ezid::Identifier id="ark:/99999/fk4rx9d523/12345">

Retrieve (Get Metadata)

>> identifier = Ezid::Identifier.find("ark:/99999/fk4rx9d523")
I, [2014-12-04T15:07:00.648676 #86655]  INFO -- : EZID GetIdentifierMetadata -- success: ark:/99999/fk4rx9d523
=> #<Ezid::Identifier id="ark:/99999/fk4rx9d523" status="public" target="http://ezid.cdlib.org/id/ark:/99999/fk4rx9d523" created="2014-12-04 20:06:02 UTC">

Update (Modify)

>> identifier.target
=> "http://ezid.cdlib.org/id/ark:/99999/fk43f4wd4v"

>> identifier.target = "http://example.com"
=> "http://example.com"

>> identifier.save
I, [2014-12-09T11:24:26.321801 #32279]  INFO -- : EZID ModifyIdentifier -- success: ark:/99999/fk43f4wd4v
=> #<Ezid::Identifier id="ark:/99999/fk43f4wd4v">

>> identifier.target
I, [2014-12-09T11:24:27.039288 #32279]  INFO -- : EZID GetIdentifierMetadata -- success: ark:/99999/fk43f4wd4v
=> "http://example.com"

Added in v1.4.0: Ezid::Identifier.modify(id, metadata) class method. In support of more efficient updating of known identifiers, this method skips the GetIdentifierMetadata request used by .find. The operation will raise the Ezid::IdentifierNotFoundError if the EZID identifier does not exist.

Delete

Identifier status must be "reserved" to delete. http://ezid.cdlib.org/doc/apidoc.html#operation-delete-identifier

>> identifier = Ezid::Identifier.mint("ark:/99999/fk4", status: "reserved")
I, [2016-03-01T22:26:08.645858 #36701]  INFO -- : EZID MintIdentifier -- success: ark:/99999/fk4pz5fm1b
=> #<Ezid::Identifier id=ark:/99999/fk4pz5fm1b>

>> identifier.delete
I, [2016-03-01T22:26:14.829731 #36701]  INFO -- : EZID GetIdentifierMetadata -- success: ark:/99999/fk4pz5fm1b
I, [2016-03-01T22:26:15.711390 #36701]  INFO -- : EZID DeleteIdentifier -- success: ark:/99999/fk4pz5fm1b
=> #<Ezid::Identifier id=ark:/99999/fk4pz5fm1b [DELETED]>

Batch Download

See http://ezid.cdlib.org/doc/apidoc.html#parameters. Repeated values should be given as an array value for the parameter key.

Added in v1.3.0: Ezid::BatchDownload class.

>> batch_download = Ezid::BatchDownload.new(:csv)
 => #<Ezid::BatchDownload format=:csv>

>> batch_download.column = ["_id", "_target"]
 => ["_id", "_target"]

>> batch_download.createdAfter = Date.today.to_time
 => 2016-02-24 00:00:00 -0500

>> batch_download
 => #<Ezid::BatchDownload column=["_id", "_target"] createdAfter=1456290000 format=:csv>

>> batch_download.url
I, [2016-02-24T18:03:40.828005 #1084]  INFO -- : EZID BatchDownload -- success: http://ezid.cdlib.org/download/4a63401e17.csv.gz
 => "http://ezid.cdlib.org/download/4a63401e17.csv.gz"

>> batch_download.file
 => /current/working/directory/4a63401e17.csv.gz

Batch

Added in v1.6.0. Ezid::Batch class.

Version 1.7.0 upgrade note: This class was originally named Ezid::BatchEnumerator, but it is not a Ruby enumerator. Ezid::Batch is the new name with the same API.

>> require 'ezid/batch'
 => true

>> batch = Ezid::Batch.new(:anvl, "spec/fixtures/anvl_batch.txt")
 => #<Ezid::Batch:0x007f87a8900308 @format=:anvl, @batch_file="spec/fixtures/anvl_batch.txt">

>> id = batch.first
 => #<Ezid::Identifier id=ark:/99999/fk4086hs23>

>> id.target
 => "http://example.com"

>> puts id.metadata
_updated: 1488227717
_target: http://example.com
_profile: erc
_ownergroup: apitest
_owner: apitest
_export: yes
_created: 1488227717
_status: public
 => nil

Metadata handling

Accessors are provided to ease the use of EZID reserved metadata elements and metadata profiles:

Reserved elements can be read and written using the name of the element without the leading underscore:

>> identifier.status                 # reads "_status" element
=> "public"

>> identifier.status = "unavailable" # writes "_status" element
=> "unavailable"

Notes:

• _crossref is an exception because crossref is also the name of a metadata profile and a special element. Use identifier._crossref to read and identifier._crossref = value to write.
• Reserved elements which are not user-writeable do not implement writers.
• Special readers are implemented for reserved elements having date/time values (_created and _updated) which convert the string time values of EZID to Ruby Time instances.

Metadata profile elements can be read and written using the name of the element, replacing the dot (".") with an underscore:

>> identifier.dc_type           # reads "dc.type" element
=> "Collection"

>> identifier.dc_type = "Image" # writes "dc.type" element
=> "Image"

Accessors are also implemented for the crossref, datacite, and erc elements as described in the EZID API documentation.

Authentication

Credentials can be provided in any -- or a combination -- of these ways:

• Environment variables:

export EZID_USER="eziduser"
export EZID_PASSWORD="ezidpass"

• Client configuration:

Ezid::Client.configure do |config|
  config.user = "eziduser"
  config.password = "ezidpass"
end

• At client initialization (only if explicitly instantiating Ezid::Client):

client = Ezid::Client.new(user: "eziduser", password: "ezidpass")

Alternate Host and Port

By default Ezid::Client connects via SSL over port 443 to the EZID host at ezid.cdlib.org, but the host, port and SSL settings may be overridden:

• By environment variables:

export EZID_HOST="localhost"
export EZID_PORT=8443
export EZID_USE_SSL="true"

• Client configuration:

Ezid::Client.configure do |config|
  config.host = "localhost"
  config.port = 8443
  config.use_ssl = true
end

• At client initialization (only if explicitly instantiating Ezid::Client):

client = Ezid::Client.new(host: "localhost", port: 80)

HTTP Timeout

The default HTTP timeout is set to 300 seconds (5 minutes). The setting can be customized:

• By environment variable:

export EZID_TIMEOUT=600

• Client configuration:

Ezid::Client.configure do |config|
  config.timeout = 600
end

• At client initialization

client = Ezid::Client.new(timeout: 600)

Test Helper

If you have tests that (directly or indirectly) use ezid-client you may want to require the test helper module:

require "ezid/test_helper"

The module provides constants:

• EZID_TEST_SHOULDER => "doi:10.5072/FK2"
• EZID_TEST_USER => "apitest"
• EZID_TEST_HOST => "ezid.cdlib.org"
• EZID_TEST_PORT => 443

The test user password is not provided - contact EZID and configure as above - or use your own EZID credentials, since all accounts can mint/create on the test shoulders.

A convenience method ezid_test_mode! is provided to configure the client to:

• authenticate as TEST_USER
• use TEST_HOST as the host and TEST_PORT as the port
• use TEST_ARK_SHOULDER as the default shoulder
• log to the null device (instead of default STDERR)

See also https://github.com/duke-libraries/ezid-client/wiki/Mock-Identifier for an example of a mock identifier object.

Running the ezid-client tests

See http://ezid.cdlib.org/doc/apidoc.html#testing-the-api.

In order to run the integration tests successfully, you must supply the password for the test account "apitest" (contact EZID). To run the test suite without the integration tests, use the rake ci task.

Dockerfile

A basic Dockerfile is provided based on Docker official Ruby image tags.

An example building an image with the latest Ruby and running the unit tests:

$ docker build -t ezid-client .
$ docker run --rm -it ezid-client bundle exec rspec ./spec/unit/

Contributing

1. Fork it ( https://github.com/[my-github-username]/ezid-client/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Acknowledgments

• Justin Gondron (@jgondron) contributed Datacite compatibility code (added in v1.8.0).
• Simon Choy (@simonmchoy) updated the Datacite schema to version 4.5 (v1.11.0).