EzID.js — API client library for Node.js
Table of Contents
This JavaScript library provides a simple asynchronous interface to the EzID API (v2)
Current supports only ARK methods; DOI is not yet supported.
npm install ezid
API Reference
The asynchronous functions all return Promises.
EzID
class
The EzID
class is used to store credentials in order to avoid
providing them with each request.
const EzID = require('ezid')
const client = new EzID ({ username: 'apitest', password: 'guess', shoulder: 'ark:/99999/fk4' })
EzID.get
Upstream documentation: https://ezid.cdlib.org/doc/apidoc.html#operation-get-identifier-metadata
This is a static function, since fetching metadata for an ARK does not require authentication.
EzID.get('ark:/48907/f3kd1xg1').then(res => {
console.log(res)
})
Example output:
{ metadata:
{ _updated: '1477087454',
_target: 'http://alexandria.ucsb.edu/lib/ark:/48907/f3kd1xg1',
'erc.ark': 'ark:/48907/f3kd1xg1',
'erc.when': '1910-1920',
_export: 'yes',
_owner: 'sb-adrl',
_ownergroup: 'sb-library',
_profile: 'erc',
'erc.who': 'London, Arthur, 1880-1920',
_created: '1460677598',
_status: 'public',
'erc.what': 'Arthur London / Gold Coast [Ghana] photograph collection' },
id: 'ark:/48907/f3kd1xg1' }
EzID#mint
Requires authentication.
Upstream documentation: https://ezid.cdlib.org/doc/apidoc.html#operation-mint-identifier
The mint
function creates an ARK with the specified metadata and an
ID decided by the upstream EzID service.
const meta = {
'_profile': 'erc',
'erc.who': 'a bird'
}
client.mint(meta).then(res => {
return console.log(res)
}).catch(err => {
console.error(err)
})
Example output:
{ metadata: {}, id: 'ark:/99999/fk4mp67k1v' }
The HTTP response from EzID will include only the new ARK, not the
metadata provided; the empty metadata
hash returned by mint
does
not mean that the ARK was not minted correctly.
Ezid#create
Requires authentication.
Upstream documentation: https://ezid.cdlib.org/doc/apidoc.html#operation-create-identifier
The create
function creates an ARK with the specified metadata and ID.
const obj = {
id: 'ark:/99999/fk4/ucsbcreate',
metadata: {
'_profile': 'erc',
'erc.who': 'a bird'
}
}
client.create(obj).then(res => {
return console.log(res)
}).catch(err => {
console.error(err)
})
Example output:
{ metadata: {}, id: 'ark:/99999/fk4/ucsbcreate' }
The HTTP response from EzID will include only the new ARK, not the
metadata provided; the empty metadata
hash returned by create
does
not mean that the ARK was not minted correctly.
Ezid#update
Requires authentication.
Upstream documentation: https://ezid.cdlib.org/doc/apidoc.html#operation-update-identifier
The update
function modifies the metadata of an existing ARK. Using
a nonexisting ARK for the id
will return an error.
const obj = {
id: 'ark:/99999/fk4/ucsbcreate',
metadata: {
'_profile': 'erc',
'erc.who': '',
'erc.what': 'an example for the readme'
}
}
client.update(obj).then(res => {
return console.log(res)
}).catch(err => {
console.error(err)
})
Example output:
{ metadata: {}, id: 'ark:/99999/fk4/ucsbcreate' }
The HTTP response from EzID will include only the ARK, not the updated
metadata; the empty metadata
hash returned by update
does not mean
that the ARK was not minted correctly.
Ezid#createOrUpdate
Requires authentication.
Upstream documentation: https://ezid.cdlib.org/doc/apidoc.html#operation-create-or-update-identifier
The createOrUpdate
function either modifies the metadata of an existing
ARK, or, if that ARK does not exist, creates it with the specified metadata.
const obj = {
id: 'ark:/99999/fk4/ucsbcreate',
metadata: {
'_profile': 'erc',
'erc.who': '',
'erc.what': 'an example for the readme'
}
}
client.update(obj).then(res => {
return console.log(res)
}).catch(err => {
console.error(err)
})
Example output:
{ metadata: {}, id: 'ark:/99999/fk4/ucsbcreate' }
The HTTP response from EzID will include only the ARK, not the
metadata; the empty metadata
hash returned by createOrUpdate
does
not mean that the ARK was not minted correctly.
Ezid#delete
Requires authentication.
Upstream documentation: https://ezid.cdlib.org/doc/apidoc.html#operation-delete-identifier
The delete
function deletes an existing ARK owned by the
authenticating user. ARKs can only be deleted when their _status
is set to reserved
.
// an object created with { '_status': 'reserved' }
client.delete('ark:/99999/fk4/ucsbres').then(res => {
return console.log(res)
}).catch(err => {
console.error(err)
})
Example output:
{ metadata: {}, id: 'ark:/99999/fk4/ucsbres' }
Developing
When running the tests, HTTP requests are mocked using
Polly. To force a re-record of HTTP
interactions, run with VCR_MODE=record npm test
(defaults is replay
).
Testing
Tests use replayer to play back HTTP requests.
Use VCR_MODE=playback npm test
to use existing fixtures, and VCR_MODE=record npm test
to record new ones. For tests requiring authentication, set the
environment variable EZID_PASS
to the EzID test API password.