NCSU-Libraries/archivesspace-api-utility

Name: archivesspace-api-utility

Owner: NCSU Libraries

Description: A lightweight utility for interacting with the ArchivesSpace API

Forked from: trevorthornton/archivesspace-api-utility

Created: 2017-10-20 16:53:48.0

Updated: 2017-10-20 16:53:50.0

Pushed: 2017-10-20 17:00:43.0

Homepage: null

Size: 37

Language: Ruby

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

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. For a more robust alternative, you might try Mark Cooper's archivespace-client.

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/trevorthornton/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):

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

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:

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

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

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

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

ults: &defaults

lopment:
: *defaults
chivesspace_host: localhost
chivesspace_port: '8089'
chivesspace_username: admin
chivesspace_password: admin
chivesspace_https: false

uction:
: *defaults
chivesspace_host: your.production.host.org
chivesspace_port: '8089'
chivesspace_username: admin
chivesspace_password: admin
chivesspace_https: false

Usage

Include the module:

ude ArchivesSpaceApiUtility

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

ion = ArchivesSpaceSession.new

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:

t::HTTPOK 200 OK readbody=true>

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

onse.body

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

.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