ARKetype provides an easy way to obtain, describe, and manage long-term identifiers for digital objects. It can be accessed via a web User Interface (UI) and a web Application Programming Interface (API). A few account management functions can be accessed from the UI only, but otherwise all of ARKetype's functionality is available through the API. This document describes a short version of the Version 2 of the ARKetype API.
Table of contents
The API allows those operations
Get identifier metadata
This allows to retrieve metadats of an identifier via a GET request to the identifier URL. This requires no identification to use.
This allows to create an identifier with a predefinied value via a PUT request. It can be asigned with metadata or left blank. (to be updated later)
User credentials are required and user need to have the permission to create an identifier with the shoulder.
This is the same than the create request above but it differs in the fact that the identifier is randomly generated rather than given and in the kind of request it uses as this one is a POST request.
This allows to update metadata of an already existing identifiers
Authentification and only the owner of the identifier or some other users can edit it.
Update identifier with the create operation
An other way to update an identifier is by using the create operation and adding ?update_if_exists=yes at the end of the URL.
That will create the identifier or update it if it already exists.
The current use of the DELETE operation is for identifiers that were created with a reserved status. This means those identifiers aren't yet public and can be fully deleted without much issue.
The alternative to deletion is to update an identifier and removes its metadata.
Those metadata are reserved and used specifically by ARKetype. They all begin with an underscore as to easily distinguishes them of the other type.
The first column, Updatable, indicates if the metadata can be updated by the user or not.
|yes||_owner||The identifier's owner. Only updatable by group administrators||jsmith|
|no||_ownergroup||The identifier's owning group, which is currently restricted to be the identifier's owner's group.||@arketype|
|no||_created||The time the identifier was created expressed as a Unix timestamp.||1300812337|
|no||_updated||The time the identifier was last updated expressed as a Unix timestamp.||1300913550|
|yes||_target||The identifier's target URL. Defaults to the identifier's ARKetype URL. That is, the default target URL for identifier foo is the self-referential URL https://www.arketype.ch/id/foo.|
|yes||_profile||The identifier's preferred metadata profile (see Metadata profiles next).||erc (default)| datacite | dc|
|yes||_status||The identifier's status||public (dfault)| reserved | unavailable|
|yes||_export||Determines if the identifier is publicized by exporting it to external indexing and harvesting services.||yes (default)| no|
|yes||_crossref||If returned, indicates that the identifier is registered with Crossref (or, in the case of a reserved identifier, will be registered), and also indicates the status of the registration process. When setting, must be set to "yes".||yes | successfully registered|
If needed, you can supply one of the following code during creation or update as placeholder.
The ARKetype system might uses the as well when needed.
|(:unal)||unallowed; intentionally suppressed|
|(:unap)||not applicable; makes no sense|
|(:unas)||unassigned (e.g., untitled)|
|(:unav)||unavailable; possibly unknown|
|(:unkn)||known to be unknown (e.g., anonymous)|
|(:none)||never had a value, never will|
|(:null)||explicitly and meaningfully empty|
|(:tba)||to be assigned or announced later|
|(:etal)||too numerous to list (et alia)|
|(:at)||the real value is at the given URL or identifier|
ARKetype was built on top of three metadata profile to use when creating an ARK
ERC is the default profile and required the following metadata.
|erc.who||The name of the entity responsible for the ARK. (author of a book, creator of a dataset or in some case, the one behind the creation of the ARK itself)|
|erc.what||A readable name describing the identifier (can be the name of a book or some title to describe the ARK)|
|erc.when||A timestamp (yan be only a year, a full date or a date range)|
The DataCite profile is commonly used for DOIs but ARKs can use them as well. It allows a better description of an item. The following metadata are the required one by ARKetype but other can be added, more details here.
The main researchers involved in producing the data, or the authors of the publication in priority order. Each name may be a corporate, institutional, or personal name.
In personal names list family name before given name, as in: Shakespeare, William
|datacite.title||A name or title by which the data or publication is known.|
|datacite.publisher||A holder of the data (e.g., an archive) or the institution which submitted the work. In the case of datasets, the publisher is the entity primarily responsible for making the data available to the research community.|
|datacite.publicationyear||The year when the data was or will be made publicly available. If an embargo period is in effect, use the year when the embargo period ends.|
|datacite.resourcetype||The general type and, optionally, specific
type of the data. The general type must be one of the
controlled vocabulary terms defined in the DataCite Metadata Scheme:
The last profile is based on the Dublin Core Metadata Element Set.
|dc.creator||The person or entity responsible for creating the resource.|
|dc.title||The name of the resource.|
|dc.publisher||The person or entity responsible fot making the resource available.|
The date the resource was made available (or when it was updated or any event worth mentioning).
The recommanded format is YYYY-MM-DD.
|dc.type||One of the following types: