Skip navigation

The ARKetype API, Quick Version 1

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

Operations

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.

Create identifier

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.

Mint identifier

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.

Update identifier

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.

Delete identifier

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.

Metadata

Internal

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.

Updatable Metadata Description Example
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

Codes

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.

Code Description
(:unac) temporarily inaccessible
(: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

Profiles

ARKetype was built on top of three metadata profile to use when creating an ARK

ERC

ERC is the default profile and required the following metadata.

Metadata Description
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)

DataCite

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.

Metadata Description
datacite.creator

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:
  • Audiovisual
  • Collection
  • Dataset
  • Event
  • Image
  • InteractiveResource
  • Model
  • PhysicalObject
  • Service
  • Software
  • Sound
  • Text
  • Workflow
  • Other
Specific types are unconstrained. If a specific type is given, it must be separated from the general type by a forward slash ("/"), as in: Image/Photograph

DublinCore

The last profile is based on the Dublin Core Metadata Element Set.

Metadata Description
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.
dc.date

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:
  • Collection
  • Dataset
  • Event
  • Image
  • InteractiveResource
  • MovingImage
  • PhysicalObject
  • Service
  • Software
  • Sound
  • StillImage
  • Text