THIS SOFTWARE IS NO LONGER SUPPORTED.
A REST client for Omeka, using the API introduced in Omeka 2.1.
Lincoln Mullen | lincoln@lincolnmullen.com | http://lincolnmullen.com
Add this line to your application's Gemfile:
gem 'omeka_client'
And then execute:
bundle install
Or install it yourself:
gem install omeka_client
See the Omeka API documentation for information about what is possible with the Omeka's API.
First, load the gem in your script:
require "omeka_client"
Next, create a client to interact with your Omeka site. You'll need your endpoint and, optionally, an API key.
client = OmekaClient::Client.new("http://localhost/omeka/api", "api_key")
# => #<OmekaClient::Client:0x007f4307937aa0>
You can read Omeka items using the following methods:
item = client.get_item(1)
# Returns a single item
client.get_all_items
# Returns an array of all the items
Each item is represented by a Ruby object. You can access the Dublin Core, Item Type, and basic metadata through methods
item.data.id
# => 1
item.data.public
# => true
item.data.added
# => "2013-07-13T04:47:08+00:00"
But since the data you probably want most are the element texts for either the Dublin Core Metadata or the Item Type Metadata, they can be accessed through methods of this type:
item.dublin_core.title
# => "Questions of the Soul"
item.dublin_core.creator
# => "Hecker, Isaac Thomas, 1819-1888."
item.item_type_metadata.binding
# => "cloth"
item.item_type_metadata.signature
# => "signed by author"
There are some helper methods to get other kinds of information from the API:
client.get_collection
client.get_all_collections
client.get_site
client.get_site.data.title
# => "Omeka Development Site"
Once you have an Omeka item, you can update it on the site, create a new item on the site, or delete it from the site. See the documentation for these functions.
# Create a new item (your local Ruby item will not point to this new item)
client.post_item(item)
# Update an item
item.dublin_core.title = "Updated via API"
client.put_item(item)
# Delete an item
client.delete_item(item)
If you want more flexibility about what you're requesting, you can use the lower-level methods. These basic PUT, POST, DELETE, and PUT methods return wrappers around the HTTP response.
client.get('items', 1)
# => #<Rest::Wrappers::NetHttpPersistentResponseWrapper:0x007fe14ba72ae0 @response=#<Net::HTTPOK 200 OK readbody=true>, @tries=1>
client.get('items', 1).code
# => 200
client.get('items', 1).body
# returns the JSON representation of the item
See the documentation for each method. You can send information to the
Omeka site using the low-level methods client.push, client.put, and
client.delete. These methods each takes a JSON object.
If you just want a raw REST connection to Omeka, then you can access the underlying instance from the Rest gem.
client.connection
You can run the tests by running rake test. You'll need to have an
Omeka site running at least 2.1 to use the tests.
You can generate the documentation by running rake yard.
This gem is licensed under the GPLv3, the same as Omeka.
This gem is based on Jim Safley's sample client for Python. And of course many thanks to all the amazing Omeka developers.