NOTE: lots of development has happened with minids. This package and repo is likely obsolete

Service	Master	Develop
CI Status
Test Coverage

minidtools

An R API client for the minid server. There's a python client, too.

A minid (Minimal Viable Identifier) is an identifier that is sufficiently simple to make creation and use trivial, while still having enough substance to make data easily findable, accessible, interoperable, and reusable (FAIR). Minids look like this: ark:/57799/b9j69h or this: minid:b9j69h.

minidtools provides functions for working with minids from an R session. The package includes lookup/resolution tools, as well as functions to mint and revise minids.

With minidtools, you can get the metadata associated with a minid, including resolving locations for the digital object a minid identifies.

Installation

You can install minidtools from github with:

# install.packages("devtools") 
devtools::install_github("bheavner/minidtools")

Quick Usage

Resolve Minid

• Get all metadata for minid

  lookup("minid:b94t3q")

• Or just get location of digital object from a minid

  get_location("minid:b94t3q")

Register User

config <- configuration()
user(config) <- "Jane Example"
email(config) <- "jexample@example.com"
orcid(config) <- "0000-0000-0000-0000" # see https://orcid.org/
register(config)

# check email to get code, then add it to the config object
code(config) <- "0000000-0000-0000-0000-000000000000"
save_configuration(config)

Load Configuration from file

config <- load_configuration()

Mint Minid

mint(minid = "./someFile.RDa", config)

Edit Minid

update(id = "ark:/99999/fk4q53tj2m",
       config = config,
       new_title = "A Better Title!",
       new_location="http://example.com/bar.txt",
       new_status = "TOMBSTONE",
       new_obsoleted_by = "ark:/99999/fk48s5xs8m")

Expanded Usage

Resolution and lookup functions

• Get title of digital object from minid

  get_title("ark:/57799/b9j69h")

• Get newer minid for minids that have status = TOMBSTONE

  get_newer("minid:b94t3q")

• get minid for file that has an identifier (e.g. a file you've downloaded after resolving a minid)

  lookup("file:./somefile.RDa", algo = "sha256")

• Retrieve all metadata for a minid or local file that has been registered

  
  my_minid <- lookup(query = "ark:/57799/b9j69h", 
                 server = "http://minid.bd2k.org/minid")

my_minid <- lookup(query = "minid:b9j69h", server = "http://minid.bd2k.org/minid")

my_minid <- lookup(query = "file:./some/file.RDa", algo = "md5", server = "http://minid.bd2k.org/minid")

or, if configuration file has been loaded

my_minid <- lookup(query = "ark:/57799/b9j69h", server = server(configuration))

* show all metadata for minid

my_minid

* Get list of locations for digitial object from metadata

locations(my_minid)

* Get other metadata values from metadata

identifier(my_minid) short_identifier(my_minid) checksum(my_minid) titles(my_minid) # returns named list with created, creator, title locations(my_minid) # returns named list with created, creator, link, uri status(my_minid) # ACTIVE or TOMBSTONED obsoleted_by(my_minid) # returns list content_key(my_minid) creator(my_minid) orcid(my_minid) created(my_minid) checksum_function(my_minid)

* Get nth (default first) location of digital object from a minid or metadata

get_location(minid = "minid:b94t3q")

get_location(minid = "ark:/57799/b9j69h", n = 1, server = "http://minid.bd2k.org/minid")

get_location(minid = "minid:b94t3q", n = 1, server = server(configuration))

get_location(my_minid)

* Get nth (default first) title of digital object from minid or metadata

get_title(minid = "minid:b94t3q")

get_title(minid = "ark:/57799/b9j69h", n = 1, server = "http://minid.bd2k.org/minid")

get_title(minid = "minid:b94t3q", n = 1, server = server(configuration))

get_title(my_minid)

* Get nth (default first) newer minid for minids that have status = TOMBSTONED 
(returns current ID if status = ACTIVE)

get_newer(minid = "minid:b94t3q")

get_newer(minid = "ark:/57799/b9j69h", n = 1, server = "http://minid.bd2k.org/minid")

get_newer(minid = "minid:b94t3q", n = 1, server = server(configuration))

get_newer(my_minid)

### User registration and configuration ###
Before using the minid API to mint or edit minids, you need to validate
your email address. You can do this with the `register()` function. When you
register, the minid server will send a unique code to your email address. You
must present this code along with your email address when minting or updating
minids.

The `register()` function takes a `configuration` object as it's argument.
Users can build a configuration object manually, e.g.

config <- configuration() user(config) <- "Jane Example" email(config) <- "jexample@example.com" orcid(config) <- "0000-0000-0000-0000" # see https://orcid.org/

As a convenience, users can also save the configuration object (including the
registration code, specified with `code(config)`) in a minid configuration file.
The minid configuration file can be formatted either as a python config-style or
JSON config file (default paths are `~/.minid/minid-config.cfg` and 
`~/.minid/minid-config.json`, respectively.)

These files look like this:
`minid-config.cfg`:

[general] minid_server: http://minid.bd2k.org/minid user: email: orcid: code:

`minid-config.json`

* Create a blank configuration object and add values

* save a configuration object to file

* load a configuration file

* get server from configuration object

* get other fields from configuration object

### Creating minids ###
* mint minid from a file path (note: will need to add location(s) subsequently)

* mint minid from configuration and minid objects

* mint minid from named lists

or

### Revising minids ###

## More information ##
More information about the project can be found at: 
[http://minid.bd2k.org/](http://minid.bd2k.org/)