README.md in ezid-client-0.6.0 vs README.md in ezid-client-0.7.0
- old
+ new
@@ -19,14 +19,16 @@
$ gem install ezid-client
## Basic Resource-oriented Usage (CRUD)
-See the test suite for more examples.
+*See the test suite for more examples.*
-Create (Mint)
+**Create** (Mint/Create)
+[Mint an identifier on a shoulder](http://ezid.cdlib.org/doc/apidoc.html#operation-mint-identifier)
+
```ruby
>> identifier = Ezid::Identifier.create(shoulder: "ark:/99999/fk4")
I, [2014-12-04T15:06:02.428445 #86655] INFO -- : EZID MINT ark:/99999/fk4 -- success: ark:/99999/fk4rx9d523
I, [2014-12-04T15:06:03.249793 #86655] INFO -- : EZID GET ark:/99999/fk4rx9d523 -- 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">
@@ -36,31 +38,63 @@
=> "public"
>> identifier.target
=> "http://ezid.cdlib.org/id/ark:/99999/fk4rx9d523"
```
-Retrieve (Get)
+A default shoulder can be configured:
```ruby
+Ezid::Client.configure do |config|
+ config.default_shoulder = "ark:/99999/fk4"
+end
+```
+
+Then identifiers can minted on the default shoulder:
+
+```ruby
+>> identifier = Ezid::Identifier.create
+I, [2014-12-09T11:22:34.499860 #32279] INFO -- : EZID MINT ark:/99999/fk4 -- success: ark:/99999/fk43f4wd4v
+I, [2014-12-09T11:22:35.317181 #32279] INFO -- : EZID GET ark:/99999/fk43f4wd4v -- success: ark:/99999/fk43f4wd4v
+=> #<Ezid::Identifier id="ark:/99999/fk43f4wd4v" status="public" target="http://ezid.cdlib.org/id/ark:/99999/fk43f4wd4v" created="2014-12-09 16:22:35 UTC">
+```
+
+[Create a specific identifier](http://ezid.cdlib.org/doc/apidoc.html#operation-create-identifier)
+
+```ruby
+>> identifier = Ezid::Identifier.create(id: "ark:/99999/fk4rx9d523/12345")
+I, [2014-12-09T11:21:42.077297 #32279] INFO -- : EZID CREATE ark:/99999/fk4rx9d523/12345 -- success: ark:/99999/fk4rx9d523/12345
+I, [2014-12-09T11:21:42.808534 #32279] INFO -- : EZID GET ark:/99999/fk4rx9d523/12345 -- success: ark:/99999/fk4rx9d523/12345
+=> #<Ezid::Identifier id="ark:/99999/fk4rx9d523/12345" status="public" target="http://ezid.cdlib.org/id/ark:/99999/fk4rx9d523/12345" created="2014-12-09 16:21:42 UTC">
+```
+
+**Retrieve** (Get Metadata)
+
+```ruby
>> identifier = Ezid::Identifier.find("ark:/99999/fk4rx9d523")
I, [2014-12-04T15:07:00.648676 #86655] INFO -- : EZID GET ark:/99999/fk4rx9d523 -- 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)
+**Update** (Modify)
```ruby
+>> identifier.target
+=> "http://ezid.cdlib.org/id/ark:/99999/fk43f4wd4v"
>> identifier.target = "http://example.com"
=> "http://example.com"
>> identifier.save
-I, [2014-12-04T15:11:57.263906 #86734] INFO -- : EZID MODIFY ark:/99999/fk4rx9d523 -- success: ark:/99999/fk4rx9d523
-I, [2014-12-04T15:11:58.099128 #86734] INFO -- : EZID GET ark:/99999/fk4rx9d523 -- success: ark:/99999/fk4rx9d523
-=> #<Ezid::Identifier id="ark:/99999/fk4rx9d523" status="public" target="http://example.com" created="2014-12-04 20:06:02 UTC">
+I, [2014-12-09T11:24:26.321801 #32279] INFO -- : EZID MODIFY ark:/99999/fk43f4wd4v -- success: ark:/99999/fk43f4wd4v
+I, [2014-12-09T11:24:27.039288 #32279] INFO -- : EZID GET ark:/99999/fk43f4wd4v -- success: ark:/99999/fk43f4wd4v
+=> #<Ezid::Identifier id="ark:/99999/fk43f4wd4v" status="public" target="http://example.com" created="2014-12-09 16:22:35 UTC">
+>> identifier.target
+=> "http://example.com"
```
-Delete
+**Delete**
+*Identifier status must be "reserved" to delete.* http://ezid.cdlib.org/doc/apidoc.html#operation-delete-identifier
+
```ruby
>> identifier = Ezid::Identifier.create(shoulder: "ark:/99999/fk4", status: "reserved")
I, [2014-12-04T15:12:39.976930 #86734] INFO -- : EZID MINT ark:/99999/fk4 -- success: ark:/99999/fk4n58pc0r
I, [2014-12-04T15:12:40.693256 #86734] INFO -- : EZID GET ark:/99999/fk4n58pc0r -- success: ark:/99999/fk4n58pc0r
=> #<Ezid::Identifier id="ark:/99999/fk4n58pc0r" status="reserved" target="http://ezid.cdlib.org/id/ark:/99999/fk4n58pc0r" created="2014-12-04 20:12:39 UTC">
@@ -71,10 +105,37 @@
## Metadata handling
Although "EZID imposes no requirements on the presence or form of citation metadata"[*](http://ezid.cdlib.org/doc/apidoc.html#metadata-requirements-mapping), `ezid-client` is intended to support the EZID [reserved metadata elements](http://ezid.cdlib.org/doc/apidoc.html#internal-metadata) and [metadata profiles](http://ezid.cdlib.org/doc/apidoc.html#metadata-profiles). While it is possible to use the client to send and receive any metadata, the object methods are geared towards the defined elements. Therefore it was seen fit, for example, to map the method `Ezid::Identifier#status` to the "_status" element. Likewise, all the reserved elements, except for "_crossref", have readers and -- for user-writable elements -- writers without the leading underscores. Since there are both "_crossref" and "crossref" elements, their accessors match the elements names. Similarly, accessors for metadata profile elements use underscores in place of dots -- for example, `Ezid::Identifer#dc_title` and `#dc_title=` for the "dc.title" element.
+**Setting default metadata values**
+
+Default metadata values can be set:
+
+```ruby
+Ezid::Client.configure do |config|
+ # set multiple defaults with a hash
+ config.identifier.defaults = {status: "reserved", profile: "dc"}
+ # or set individual elements
+ config.identifier.defaults[:status] = "reserved"
+ config.identifier.defaults[:profile] = "dc"
+end
+```
+
+Then new identifiers will receive the defaults:
+
+```ruby
+>> identifier = Ezid::Identifier.create(shoulder: "ark:/99999/fk4")
+I, [2014-12-09T11:38:37.335136 #32279] INFO -- : EZID MINT ark:/99999/fk4 -- success: ark:/99999/fk4zs2w500
+I, [2014-12-09T11:38:38.153546 #32279] INFO -- : EZID GET ark:/99999/fk4zs2w500 -- success: ark:/99999/fk4zs2w500
+=> #<Ezid::Identifier id="ark:/99999/fk4zs2w500" status="reserved" target="http://ezid.cdlib.org/id/ark:/99999/fk4zs2w500" created="2014-12-09 16:38:38 UTC">
+>> identifier.profile
+=> "dc"
+>> identifier.status
+=> "reserved"
+```
+
## Authentication
Credentials can be provided in any -- or a combination -- of these ways:
- Environment variables `EZID_USER` and/or `EZID_PASSWORD`;
@@ -92,10 +153,32 @@
```ruby
client = Ezid::Client.new(user: "eziduser", password: "ezidpass")
```
-## Running the tests
+## Test Helper
+
+If you have tests that (directly or indirectly) use `ezid-client` you may want to require the test helper module:
+
+```ruby
+require "ezid/test_helper"
+```
+
+The module provides constants:
+
+- `TEST_ARK_SHOULDER` => "ark:/99999/fk4"
+- `TEST_DOI_SHOULDER` => "doi:10.5072/FK2"
+- `TEST_USER` => "apitest"
+
+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_ARK_SHOULDER` as the default shoulder
+- log to the null device (instead of default STDERR)
+
+## 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.