API-Zugriff (nur EN)

ARCHE provides several interfaces to search and retrieve its data in programmatic ways.

ARCHE APIs are built using microservices. It means the ARCHE core service provides only a basic functionality for creating, reading, updating, and deleting (CRUD) while all other features (e.g., OAI-PMH) are handled by separate small services (called dissemination services) built on top of the core API.

ARCHE Core API #

The main ARCHE API provides the core functionality for searching, reading, creating, updating, and deleting. It allows you to access a resource’s binary content as well as its metadata in various RDF serialisations (turtle, RDF/XML, JSON-LD, n-triples), e.g., to get RDF metadata of a collection (let’s say the https://hdl.handle.net/21.11115/0000-000C-D89B-2 one) and all its direct children in the turtle format you do a call like:
https://arche.acdh.oeaw.ac.at/api/search?property[]=https%3A%2F%2Fvocabs.acdh.oeaw.ac.at%2Fschema%23hasIdentifier&value[]=https%3A%2F%2Fhdl.handle.net%2F21.11115%2F0000-000C-D89B-2&readMode=1_0_0_0&format=text%2Fturtle

Remarks:

A technical documentation of the core API in the OpenAPI 3 standard can be found on the SwaggerHub.
There are two guides discussing how to use the API available:
- Metadata API guide
- Search API guide
If you think the RDF can be parsed with regular expressions or assume some constant structure of the RDF-XML or JSON-LD serialisation, please first read the Serialization formats chapter of the Using RDF in webapps guide and then switch to using a dedicated RDF parsing library (they exist for all major programming languages).
If you are new to RDF, it is highly recommended to read:
- Using RDF in webapps basics
- RDF compacting
If you process the output programmatically, it is advised to use the n-triples format to ensure best performance, as detailed in the Metadata API performance documentation.
If you are using PHP, there is a library providing bindings to this API: the arche-lib.

Response Format Negotiation #

All ARCHE resource URIs beginning with https://hdl.handle.net/ and https://id.acdh.oeaw.ac.at/ (so called PIDs) allow you to specify a desired serialisation of the requested resource.

If there is a dissemination service capable of providing a requested serialisation, you will be automatically redirected to it. If not, you will be redirected to the “raw” resource content, i.e., a binary file or metadata for resources without binary content (e.g., information about a person).

The requested format can be specified by providing a media type (MIME type) or the name of the desired dissemination service either in the HTTP Accept header or in the format request query parameter (please note that the https://hdl.handle.net service uses @ instead of ?to separate the query parameters from rest of the URL), e.g.:

To get a thumbnail image of a given resource, you can request it in the image/png media type or explicitly use the thumbnail dissemination service, e.g.:
https://id.acdh.oeaw.ac.at/schnitzler/bahrschnitzler?format=image%2Fpng,
https://id.acdh.oeaw.ac.at/schnitzler/bahrschnitzler?format=thumbnail,
https://hdl.handle.net/21.11115/0000-000E-C8A6-5@format=image%2Fpng,
https://hdl.handle.net/21.11115/0000-000E-C8A6-5@format=thumbnail.
To get a resource’s metadata in the turtle format, you can request it in the text/turtle media type or use the metadata dissemination service, e.g.:
https://id.acdh.oeaw.ac.at/schnitzler/bahrschnitzler?format=test%2Fturtle,
https://id.acdh.oeaw.ac.at/schnitzler/bahrschnitzler?format=metadata,
https://hdl.handle.net/21.11115/0000-000E-C8A6-5@format=text%2Fturtle,
https://hdl.handle.net/21.11115/0000-000E-C8A6-5@format=metadata.
To get a bibliographic entry of a resource in BibLaTeX format, you can request it with the application/x-bibtex media type or use the biblatex dissemination service, e.g.:
https://id.acdh.oeaw.ac.at/schnitzler/bahrschnitzler?format=application%2Fx-bibtex,
https://id.acdh.oeaw.ac.at/schnitzler/bahrschnitzler?format=biblatex,
https://hdl.handle.net/21.11115/0000-000E-C8A6-5@format=application%2Fx-bibtex,
https://hdl.handle.net/21.11115/0000-000E-C8A6-5@format=biblatex.

Practical tips:

To get a list of all dissemination services available for a given resource you can use the special value of the format parameter __list__:
https://id.acdh.oeaw.ac.at/schnitzler/bahrschnitzler?format=__list__
https://hdl.handle.net/21.11115/0000-000E-C8A6-5@format=__list__.
Examples above do not show usage of the HTTP Accept header as there is no way to encode it in the URL but a https://id.acdh.oeaw.ac.at/schnitzler/bahrschnitzler?format=image%2Fpng leads to the same response as curl -L -H 'image/png' https://id.acdh.oeaw.ac.at/schnitzler/bahrschnitzler
The https://hdl.handle.net PIDs service encodes query parameters in unusual way
- @ is used instead of ? to separate request path and query
- a + character in the request query has to be encoded as %252B
so e.g., to request a https://hdl.handle.net/21.11115/0000-000E-C8A6-5 resource in the application/rdf+xml format the URL has to be https://hdl.handle.net/21.11115/0000-000E-C8A6-5@format=application%2Frdf%252Bxml
Some dissemination services can only process given kind of ARCHE resources, e.g., the IIIF dissemination service can only process images.
A more in detail description of the resolution process is provided in the ARCHE Suite Dissemination Services documentation.

RDF #

An RDF serialisation of any ARCHE resource metadata can be obtained by requesting a resource in the desired RDF serialisation format (text/turtle, application/n-triples, application/rdf+xml or application/ld+json; text/html is also supported and returns a simple HTML view of the metadata) – see the Response Format Negotation chapter above, e.g.
https://id.acdh.oeaw.ac.at/schnitzler/bahrschnitzler?format=application%2Frdf%2Bxml,
https://hdl.handle.net/21.11115/0000-000E-C8A6-5@format=application%2Frdf%252Bxml.

or curl -L -H 'Accept: application/rdf+xml' 'https://id.acdh.oeaw.ac.at/schnitzler/bahrschnitzler'

Practical tips:

If you try it out in a browser please be aware that browsers always add a text/html HTTP Accept header to the request. Because of that you will always get an HTML serialisation of the metadata. Use a dedicated tool like curl or Postman if you want better control over HTTP requests you are sending by hand.
The https://hdl.handle.net PIDs service encodes query parameters in unusual way
- @ is used instead of ? to separate request path and query
- a + character in the request query has to be encoded as %252B
(see the URL in the example above).
The Metadata API guide provides a detailed instructions on how to fetch a desired amount of metadata in a single metadata API call.
If you are new to RDF, it is highly recommended to read:
- Using RDF in webapps basics
- RDF compacting
The best way of dealing with RDF output provided by our metadata and search endpoints is to use dedicated RDF parsing libraries (they exist for all major programming languages). Parsing RDF with regular expressions or assuming a particular structure of an XML or JSON serialisation tree is error-prone because the same RDF data can be serialised into turtle, XML or JSON in various ways (see the Using RDF in webapps guide).
If you are processing the metadata programmatically, use the application/n-triples format. It’s the fastest both on server and client side and reduces the load on the server side as documented in the Metadata API performance documentation.

Citations #

Bibliographic entries in the BibLaTeX and CSL-JSON formats as well as formatted citations can be obtained for any ARCHE resource by requesting its dissemination in one of application/x-bibtex, application/vnd.citationstyles.csl+json, apa-6th-edition or vancouver formats (see the Response Format Negotiation section above for details), e.g. https://id.acdh.oeaw.ac.at/schnitzler/bahrschnitzler?format=apa-6th-edition.

The service takes two optional request query parameters:

lang – preferred language (e.g., en or de). While there is no guarantee of values (like title) being available in a requested language, they will be used if present, e.g., compare https://id.acdh.oeaw.ac.at/dial?format=biblatex&lang=en and https://id.acdh.oeaw.ac.at/dial?format=biblatex&lang=de.
override – a bibliographic entry in BibLaTeX or CSL-JSON format that overrides and/or extends field values mapped from the repository metadata. The returned entry will be a merge of the data coming from the repository and data provided using this parameter. The data provided along this parameter will take precedence over data coming from the repository. More information is included in the README of arche-biblatex service on GitHub. A basic example providing an alternative title for the resource: https://id.acdh.oeaw.ac.at/dial?format=apa-6th-edition&override=%7B%22title%22%3A%22Overwritten%20title%22%7D.

Thumbnails #

Thumbnails for all ARCHE resources can be obtained by requesting its dissemination in the thumbnail format (see the Response Format Negotiation section above for details), e.g.
https://id.acdh.oeaw.ac.at/digitarium/facs/17030808-000.png?format=thumbnail
https://hdl.handle.net/21.11115/0000-0010-3310-2@format=thumbnail.

The service takes two optional request query parameters width and height (with default values of 100) allowing to specify the thumbnail image size in pixels, e.g. https://id.acdh.oeaw.ac.at/digitarium/facs/17030808-000.png?format=thumbnail&width=700&height=600. If only one of them is specified, the other is computed automatically based on the returned image aspect ratio

Reconcilation Service API (OpenRefine) #

ARCHE provides the Reconciliation Service API endpoint which can be used e.g. in OpenRefine.

The endpoint URL that can be used to connect ARCHE to OpenRefine is https://arche.acdh.oeaw.ac.at/openrefine/reconcile.

GLB (3D models) #

To assure smooth on-line viewing of 3D models disregarding their size, ARCHE provides a proxy service which serves a (cached) 3D model version downscaled so its size is no bigger than 30 MB.

To request an on-line viewing friendly version of the GLB 3D model resource, please request its dissemination either in glb or model/gltf-binary format (see the Response Format Negotiation section above for details).

IIIF #

Raster images (TIFF, PNG, JPEG) stored in ARCHE can be accessed through the IIIF Image API 2.1. The IIIF endpoint is implemented with the Loris IIIF Image Server. To access an image’s IIIF endpoint you should request its dissemination in one of the following formats (see the Response Format Negotiation section above for details):

raster image formats: image/jpeg, image/png, image/webp, image/gif
special format value used to request the image information JSON: image/json (please note that if this format is requested, then the param query parameter is omitted)

E.g.: https://id.acdh.oeaw.ac.at/ODeeg/Collections/AT-Vienna-KHM/KHM-ANSA-IV1/Photos/KHM-ANSA-IV1_im01.tif?format=image%2Fpng.

You can use the param query parameter to pass additional IIIF Image API parameters. Passing the param parameter overwrites the response format requested by the HTTP Accept header and/or the format parameter. E.g.

https://id.acdh.oeaw.ac.at/ODeeg/Collections/AT-Vienna-KHM/KHM-ANSA-IV1/Photos/KHM-ANSA-IV1_im01.tif?format=image%2Fpng&param=full/full/90/default.png to get the image rotated by 90 degrees and converted to PNG.
Note that https://id.acdh.oeaw.ac.at/ODeeg/Collections/AT-Vienna-KHM/KHM-ANSA-IV1/Photos/KHM-ANSA-IV1_im01.tif?format=image%2Fwebp&param=full/full/90/default.png will still return the PNG as the format coming from the param parameter value takes precedence over the format requested in the format parameter.
https://id.acdh.oeaw.ac.at/pez-nachlass/425627.tif?format=image%2Fjson to retrieve the image’s info.json.

Please consult the IIIF Image API documentation for the list of available IIIF Image API parameters.

IIIF presentation manifest #

For collections with established order of children ARCHE can generate a IIIF presentation manifests.

To get the manifest of a given collection, request its dissemination in the iiifmanifest format (see the Response Format Negotiation section above for details), e.g.
https://id.acdh.oeaw.ac.at/emt/kasten_blau_45_15_0449?format=iiifmanifest
https://hdl.handle.net/21.11115/0000-0016-7178-2@format=iiifmanifest

Requesting manifest of a resource returns the manifest of a collection the resource belongs to, e.g.
https://id.acdh.oeaw.ac.at/emt/kasten_blau_45_15_0449___0001.jpg?format=iiifmanifest
https://hdl.handle.net/21.11115/0000-0016-649D-7@format=iiifmanifest

Requesting manifest of a collection which children do not have an established order ends up with an error, e.g.
https://id.acdh.oeaw.ac.at/iuenna/01_GLO/01_06_Text_Tabellen/01_06_02_Protokolle?format=iiifmanifest

Requesting manifest of a collection with no images returns an empty manifest.

It is also possible to request a IIIF collection manifest. In this case requesting the iiifmanifest format should be coupled with the mode=collection request query parameter (the collection mode will be also chosen automatically if a requested collection does not contain any resources but only subcollections), e.g.
https://id.acdh.oeaw.ac.at/stams?format=iiifmanifest&mode=collection

The IIIF presentation manifest dissemination service can also generate an image list in the OpenSeadragon image viewer’s config format. In this case requesting the iiifmanifest format should be coupled with the mode=images request query parameter, e.g.
https://id.acdh.oeaw.ac.at/emt/kasten_blau_45_15_0449?format=iiifmanifest&mode=images
https://hdl.handle.net/21.11115/0000-0016-7178-2@format=iiifmanifest&mode=images
https://id.acdh.oeaw.ac.at/emt/kasten_blau_45_15_0449___0002.jpg?format=iiifmanifest&mode=images
https://hdl.handle.net/21.11115/0000-0016-649F-5@format=iiifmanifest&mode=images

OAI-PMH and External Aggregators #

ARCHE is harvested by multiple aggregators using the OAI-PMH protocol.

The OAI-PMH endpoint is https://arche.acdh.oeaw.ac.at/oaipmh/, e.g.

ARCHE provides the OAI-PMH metadata in the following representations:

Dublin Core for all resources (sample record)
ARCHE metadata schema serialised as RDF/XML for all resources (sample record)
DataCite for resources in the openaire_data OAI-PMH set harvested by the OpenAIRE (list records URL)
Europeana Data Model for resources in the kulturpool OAI-PMH set harvested by the Kulturpool aggregator and subsequentially by the Europeana aggregator (list records URL)
CMDI for resources in the clarin-vlo OAI-PMH set harvested by the CLARIN VLO aggregator (list records URL)
AO-Cat for resources in the ariadne OAI-PMH set, harvested by the ARIADNE aggregator (list records URL)