README.md in ezid-client-0.1.0 vs README.md in ezid-client-0.1.1

@@ -14,54 +14,112 @@
 
 Or install it yourself as:
 
     $ gem install ezid-client
 
-## Usage
+## Basic Usage
 
-Create a client
+See `Ezid::Client` class for details.
 
-```ruby
->> client = Ezid::Client.new(user: "apitest", password: "********")
-=> #<Ezid::Client:0x007f857c23ca40 @user="apitest", @password="********", @session=#<Ezid::Session:0x007f857c2515a8 @cookie="sessionid=quyclw5bbnwsay0qh05isalt86xj5o1l">>
+**Create a client**
+
 ```
+>> client = Ezid::Client.new(user: "apitest")
+=> #<Ezid::Client:0x007f8ce651a890 , @user="apitest", @password="********">
+```
 
-Mint an identifier
+Initialize with a block (wraps in a session)
 
-```ruby
->> response = client.mint_identifier("ark:/99999/fk4")
-=> #<Ezid::Response:0x007f857c488010 @http_response=#<Net::HTTPCreated 201 CREATED readbody=true>, @metadata=#<Ezid::Metadata:0x007f857c488448 @elements={}>, @result="success", @message="ark:/99999/fk4988cc8j">
->> response.identifier
-=> "ark:/99999/fk4988cc8j"
 ```
+>> Ezid::Client.new(user: "apitest") do |client|
+?>   client.server_status("*")
+>> end
+I, [2014-11-20T13:23:23.120797 #86059]  INFO -- : success: session cookie returned
+I, [2014-11-20T13:23:25.336596 #86059]  INFO -- : success: EZID is up
+I, [2014-11-20T13:23:25.804790 #86059]  INFO -- : success: authentication credentials flushed
+=> #<Ezid::Client:0x007faa5a6a9ee0 , @user="apitest", @password="********">
+```
 
-Modify identifier metadata
+**Login**
 
-```ruby
->> metadata = Ezid::Metadata.new("dc.type" => "Image")
-=> #<Ezid::Metadata:0x007f857c251c88 @elements={"dc.type"=>"Image"}>
->> response = client.modify_identifier("ark:/99999/fk4988cc8j", metadata)
-=> #<Ezid::Response:0x007f857c53ab20 @http_response=#<Net::HTTPOK 200 OK readbody=true>, @metadata=#<Ezid::Metadata:0x007f857c53aa30 @elements={}>, @result="success", @message="ark:/99999/fk4988cc8j">
+Note that login is not required to send authenticated requests; it merely establishes a session.  See http://ezid.cdlib.org/doc/apidoc.html#authentication.
+
 ```
+>> client.login
+I, [2014-11-20T13:10:50.958378 #85954]  INFO -- : success: session cookie returned
+=> #<Ezid::Client:0x007f8ce651a890 LOGGED_IN, @user="apitest", @password="********">
+```
 
-Get identifier metadata
+**Mint an identifier**
 
 ```
->> response = client.get_identifier_metadata("ark:/99999/fk4988cc8j")
-=> #<Ezid::Response:0x007f857c50a060 @http_response=#<Net::HTTPOK 200 OK readbody=true>, @metadata=#<Ezid::Metadata:0x007f857c509f48 @elements={"_updated"=>"1416436386", "_target"=>"http://ezid.cdlib.org/id/ark:/99999/fk4988cc8j", "_profile"=>"erc", "dc.type"=>"Image", "_ownergroup"=>"apitest", "_owner"=>"apitest", "_export"=>"yes", "_created"=>"1416436287", "_status"=>"public"}>, @result="success", @message="ark:/99999/fk4988cc8j">
->> response.metadata["dc.type"]
-=> "Image"
+>> response = client.mint_identifier("ark:/99999/fk4")
+I, [2014-11-20T13:11:25.894128 #85954]  INFO -- : success: ark:/99999/fk4fn19h87
+=> #<Net::HTTPCreated 201 CREATED readbody=true>
+>> response.identifier
+=> "ark:/99999/fk4fn19h87"
+```
+
+**Get identifier metadata**
+
+```
+>> response = client.get_identifier_metadata(response.identifier)
+I, [2014-11-20T13:12:08.700287 #85954]  INFO -- : success: ark:/99999/fk4fn19h87
+=> #<Net::HTTPOK 200 OK readbody=true>
 >> puts response.metadata
-_updated: 1416436386
-_target: http://ezid.cdlib.org/id/ark:/99999/fk4988cc8j
+_updated: 1416507086
+_target: http://ezid.cdlib.org/id/ark:/99999/fk4fn19h87
 _profile: erc
-dc.type: Image
 _ownergroup: apitest
 _owner: apitest
 _export: yes
-_created: 1416436287
+_created: 1416507086
 _status: public
+=> nil
 ```
+
+**Logout**
+
+```
+>> client.logout
+I, [2014-11-20T13:18:47.213566 #86059]  INFO -- : success: authentication credentials flushed
+=> #<Ezid::Client:0x007faa5a712350 , @user="apitest", @password="********">
+```
+
+## Resource-oriented Usage
+
+Experimental -- see `Ezid::Identifier`.
+
+## Metadata handling
+
+See `Ezid::Metadata`.
+
+## Authentication
+
+Credentials can be provided in any -- or a combination -- of these ways:
+
+- Environment variables `EZID_USER` and/or `EZID_PASSWORD`;
+
+- Client configuration:
+
+```ruby
+Ezid::Client.configure do |config|
+  config.user = "eziduser"
+  config.password = "ezidpass"
+end
+```
+
+- At client initialization:
+
+```ruby
+client = Ezid::Client.new(user: "eziduser", password: "ezidpass")
+```
+
+## Running the tests
+
+By default the tests authenticate as user "apitest"; the password is not provided -- see http://ezid.cdlib.org/doc/apidoc.html#testing-the-api.
+
+The test suite uses [VCR](https://relishapp.com/vcr/vcr) and [WebMock](https://github.com/bblimke/webmock) to stub requests and responses after the first run.  The VCR "cassettes" are written to `spec/cassettes` and may be cleared with the rake task `test:clean`.
 
 ## Contributing
 
 1. Fork it ( https://github.com/[my-github-username]/ezid-client/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)