ArchivesSpace API Utility

A Ruby gem to facilitate interaction with the ArchivesSpace REST API. Provides basic functionality for establishing and maintaining a session and performing GET and POST operations (using Ruby's Net::HTTP library). This gem works at a fairly low level and just makes it a bit easier to interact with the API in your Ruby code, but without a lot of abstraction.

Documentation on the ArchivesSpace API can be found at http://archivesspace.github.io/archivesspace/doc/file.API.html.

Installation

Add this line to your application's Gemfile:

gem 'archivesspace-api-utility', :git => "https://github.com/NCSU-Libraries/archivesspace-api-utility.git"

Then execute:

bundle install

Configuration

This gem requires an instance of ArchivesSpace to be running on an accessible server, which can be configured like this (modified as appropriate):

ArchivesSpaceApiUtility.configure do |config|
  config.host = 'localhost'
  config.port = 8089 # backend port number
  config.username = 'admin'
  config.password = 'admin'
  config.https = false
end

NOTE: If ArchivesSpace components are running under separate subdomains rather than on different ports on the same host, set config.port to nil and provide the appropriate host for the backend. This will often be the case if ArchivesSpace is accessed via https.

This can be included in a script (after including ArchivesSpaceApiUtility).

If you're working in Rails, you can just create a file called archivesspace_config.rb in /config/initializers and put the configuration in there.

To configure the gem to use ENV vars, make sure this is in your application.rb file:

ENV.update YAML.load_file('config/application.yml')[Rails.env] rescue {}

Then create /config/initializers/archivesspace_config.rb that looks like this:

ArchivesSpaceApiUtility.configure do |config|
  config.host = ENV['archivesspace_host']
  config.port = ENV['archivesspace_port'].to_i
  config.username = ENV['archivesspace_username']
  config.password = ENV['archivesspace_password']
  config.https = ENV['archivesspace_https']
end

Then specify environment-specific options in application.yml, for example:

defaults: &defaults

development:
  <<: *defaults
  archivesspace_host: localhost
  archivesspace_port: '8089'
  archivesspace_username: admin
  archivesspace_password: admin
  archivesspace_https: false

production:
  <<: *defaults
  archivesspace_host: your.production.host.org
  archivesspace_port: '8089'
  archivesspace_username: admin
  archivesspace_password: admin
  archivesspace_https: false

Usage

Start a session (assigned to a variable for re-use):

<<<<<<< HEAD
include ArchivesSpaceApiUtility

Start a session (aasigned to a variable for re-use):

session = ArchivesSpaceSession.new
=======
session = ArchivesSpaceApiUtility::ArchivesSpaceSession.new
>>>>>>> 60901cd0cecdeb55c9d9a3eb1979dc2a6a21c021

Then use get or post to do what you need to do...

get(path,params={},headers={})

• path - See ArchivesSpace API documentation for available paths for GET
• params - optional query params (to append to URL)
• headers - optional HTTP Request headers

Make a GET request:

response = session.get('/repositories')

That returns a NET::HTTPResponse object:

#<Net::HTTPOK 200 OK readbody=true>

To get the response body (a JSON object) just do:

response.body

And if you want that as a hash just use Ruby's JSON library

JSON.parse(response.body)

post(path,data,headers={})

• path - See ArchivesSpace API documentation for available paths for POST
• data - Data to be sent in request body. This will be sent as a JSON object (you can pass in a hash and it will be converted to JSON before the request is made). The content and validity of your post data is between you and ArchivesSpace - if there is a problem the API should return a response explaining what the problem was. A bit of guidance can be found by looking at the JSON schema documents here.
• headers - optional HTTP Request headers

Just like get, post will return a NET::HTTPResponse object.

License

See MIT-LICENSE