Skip navigation

The ARKetype API, 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 is a rework of this page.

The current test shoulder for https://www.arketype.ch is ark:/99999/fk3

Table of contents

Authentification

Some of the path required an authentication. You can choose to use HTTP Basic Authentification which allow you to send basic authentication with every request. Alternatively you can use One Time Login which allow you to log one time and use the response cookie to authentificate after that.

HTTP Basic Authentification Examples

                        curl -u $username:$password -X PUT https://www.arketype.ch
                     
import base64, urllib2
r = urllib2.Request("https://www.arketype.ch/...")
r.add_header("Authorization", "Basic " + base64.b64encode("username:password"))

One Time Login Examples

                           curl -vu $username:$password -X PUT https://www.arketype.ch/login
                        
                           # Generate cookie
import urllib2
c = urllib2.urlopen("https://www.arketype.ch/login")
cookie = c.headers["Set-Cookie"].split(";")[0]
# Use cookie
r = urllib2.Request("https://www.arketype.ch")
r.add_header("Cookie", cookie)
                           

Request & response

Request and response are all in the content type "text/plain" using UTF-8 charset encoding.

The data model for the metadatas is a single-valued dictionary of element name/value pairs. Single-valued means it expect each element name not to be repeated.Leading and whitespace are not taken in account. An empty value is not a valid entry when creating an identifier. If a metadata value is updated with one. It is considered to be deleted.

# A line starting with a # is a comment that will be ignored
who: Doe, John
what: An element that is on several
   lines will be treated as one
   as long as each line after the
   first starts with a whitespace.
when: 2019

You need to be careful to escape any special characters appearing like, for instance, colons, percent or any line terminators (\r, \n, ...)

Error reporting

An error is indicated by two elements, an HTTP status code and a message in the form of "error: reason". Not every requests will show both responses unless you specify it.

For example, with a curl, you need to specify the -i parameter to show both the HTTP status code and the message, by default it will only show the message. To display only the status code, you can use -I (uppercase i).

                              > curl -i https://www.arketype.ch/id/ark:/99999/fk3_not_exist

HTTP/1.0 400 Bad Request
Date: Thu, 02 Sep 2021 09:49:53 GMT
Server: WSGIServer/0.1 Python/2.7.18
Vary: Accept-Language, Cookie
Content-Length: 39
Content-Type: text/plain; charset=UTF-8
Content-Language: en

error: bad request - no such identifier

Operations

The API allows those operations

Get status

This allows you to check for the status of ARKetype

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

https://github.com/HEG-INCIPIT/ezid-client-tools/blob/heg/batch-register.py

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, 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 (default)| 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

Identifier status

Each identifier has a status that is defined by the _status metadata seen in the table above. It can take 3 values:

public

The default value. It makes the identifier available to everyone.

reserved

Identifiers with this status are only known to ARKetype. It may be used to reserve an identifier without advertising resolver of its existence. An identifier with this can be fully deleted.

unavailable

The identifier is public, but its metadata isn't. A reason for the unavailability can be passed at the same time with a pipe, e.g. "unavailable | removed by author".

The identifier redirects to a tombstone page regardless of its target url.


The status can be changed at any time by providing the "_status" metadata with the following rules:

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 (can 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.

so it lo
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

Python Tools

We provide some python tools that are linked to the api, for example, to batch upload datas from a CSV file.

Batch Register

This script allows you to reigster several identifiers contained in a csv files.

It requires a mapping file alongside the csv file.

Usage:

                                                                                          batch-register.py -c $username -s $shoulder mapping_file csv_file
                                                                                       

The mapping files can contains any of the metadatas shown above with the corresponding line with a profile parameters to indicates which one should be used, for instance:

_profile = erc
_target  = $1
erc.who  = $2
erc.what = $3
erc.when = $3

Download: