Difference between revisions of "APE API documentation"

Revision as of 08:25, 4 May 2016

APE API

The Archives Portal Europe helps people to search for and retrieve archival descriptions harvested from archival institutons throughout Europe. These services are available as an Application Programming Interface (API) as well. Request and response parameters are provided and delivered in JSON. This enables every programmer to create an (online) user interface for searching in and retrieving of archival descriptions.

We expect readers of this documentation to:

• know how to develop with a RESTful API and JSON
• understand the hierarchical data structures in archival descriptions
• have a notion about the XML-data standard Encoded Archival Description (EAD) 2002
• have a notion about the way data is copied ('harvested') in EAD-format from Collection Management Systems at archival institutions

The services

In the current version there are three services:

• POST request: /search/ead
• GET request: /content/{id}
• GET request: /content/descriptiveUnit/{id}

The current endpoint of the API is http://development.archivesportaleurope.net/ApeApi/services
Note: after release of version 1.0 we want it to be: http://api.archivesportaleurope.net/services.
Via this URL you can access the ApeApi Explorer were you can try the services and see the responses: http://www.archivesportaleurope.net/ApeApi/#!/search/search.

Future work

In the current version search and retrieve of archival descriptions are provided. We plan to expand this functionality with searching and retrieving of:

• descriptions of records creators
• information on archival institutions
• person names in the archival records

API Key

In order for Archives Portal Europe to monitor the use of the API, you need to request an API-key to be able to use the API. The API-key can be requested via the option API INFORMATION on the homepage of the portal. Because the API is for now only working on the development server, at the moment the API-key can be requested via this url: https://development.archivesportaleurope.net/get-api-key
Note: after release of version 1.0 this option will be available via: https://www.archivesportaleurope.net/get-api-key

You need to add a parameter "APIkey" to the header of your request. eg.

 	'APIkey' : 'put_your_personal_API-key_here'

Versioning

Depending on the version of the API that you want to use, the accept parameter in the header must be set to a specific Content Type. For version 1.0 this is: application/vnd.ape-v1+json

eg.

 	'accept' : 'application/vnd.ape-v1+json'

The /search/ead service

Request url: TODO This service is a POST-request.

Request parameters

Three request parameters can be used to do a search in archival descriptions.

eg.

{
  "query": "nepal",
  "count": 5,
  "startIndex": 0
}

query

Containing the searchterm(s). Required.

count

The resultlist is delivered in chunks of a certain size. Request parameter "count" describes the number of results that are in one chunk. Optional. Default value is 5.

startIndex

Request parameter "startIndex" enables you to select the results that you want to have. Counting starts at zero. If "count" = 5, the second chunk starts with startIndex 5, the following at startIndex 10, etc. Optional. Default value is 0.

Response parameters

The response contains a list of the descriptions where the requested search-term(s) was/were found.

eg.

{
  "totalResults": 1,
  "start": 0,
  "totalPages": 1,
  "eadSearchResults": [
    {
      "id": "C4134966",
      "unitId": "2.05.313 - 2.77",
      "unitTitle": "Nepal",
      "unitTitleWithHighlighting": "<em>Nepal</em>",
      "scopeContent": "",
      "scopeContentWithHighlighting": "",
      "fondsUnitTitle": "Inventaris van het code-archief van het Ministerie van Buitenlandse Zaken, 1965-1974",
      "fondsUnitId": "2.05.313",
      "repository": "Nationaal Archief",
      "country": "NETHERLANDS",
      "language": "",
      "langMaterial": "",
      "unitDate": "",
      "repositoryCode": "NL-HaNA",
      "hasDigitalObject": false,
      "docType": "Descriptive Unit"
    }
  ]
}

totalResults

The response parameter "totalResults" gives the number of results.

start

The response parameter "start" gives the number of the chunk you requested.

totalPages

The response parameter "totalPages" gives the number of chunks.

eadSearchResults

Enumeration of the results. A result could be a holdings guide, a source guide, a finding aid, or a descriptive unit (ie. a sublevel component).

The /content/{id} service

Request url: TODO.

This service is a GET-request.

Request parameters

id

Internal APE identifier of a Finding Aid (id is starting with "F"), a Holdings Guide (id's starting with "H"), a Source Guide (id is starting with "S"). Descriptive Units result in other information, so a separate request is developed, called /content/descriptiveUnit. In this service, if the identifier does not start with a "F", "H" or "S" you will get an error message. This parameter is required.

Response parameters

{
  "id": "F883",
  "unitId": "3066",
  "unitTitle": "Partij van de Arbeid (P.v.d.A.), Statenfractie PvdA Gelderland",
  "repositoryId": 363,
  "repository": "Gelders Archief",
  "content": {
   --- skip ---
  }
}

id

Internal APE identifier of the Finding Aid, Holdings Guide or Source Guide. The same as your request parameter "id".

unitId

Original identifier of the information provided by the repository.

unitTitle

Title of the information provided by the repository.

repositoryId

Internal APE identifier of the repository.

repository

Name of the repository.

content

Information in EAD-format, serialized as JSON. This part could potentially contain all the elements that can be part of an EAD/XML-document.

The /content/descriptiveUnit/{id} service

Request url: TODO

This service is a GET-request.

Request parameters

id

Internal APE identifier of a Descriptive Unit (id is starting with "C"). In this service, if the identifier does not start with a "C", you will get an error message. This parameter is required.

Response parameters

{
  "id": "C4134966",
  "unitId": "2.05.313 - 2.77",
  "unitTitle": "Nepal",
  "repositoryId": 361,
  "repository": "Nationaal Archief",
  "content": {
   --- skip ---
  }
}

id

Internal APE identifier of the Descriptive Unit. The same as your request parameter "id".

unitId

Original identifier of the information provided by the repository.

unitTitle

Title of the information provided by the repository.

repositoryId

Internal APE identifier of the repository.

repository

Name of the repository.

content

Information in EAD-format, serialized as JSON. This part could potentially contain all the elements that can be part of a Component-element (<c>) of an EAD/XML-document.