Difference between revisions of "APE API documentation"

From Archives Portal Europe Wiki
Jump to: navigation, search
(→‎Versioning)
 
(11 intermediate revisions by the same user not shown)
Line 8: Line 8:
 
<div><br/>__TOC__<br/></div>
 
<div><br/>__TOC__<br/></div>
 
= The services =
 
= The services =
−
In the current version (v2.0.0), various services are available. The endpoint of the API is [https://api.archivesportaleurope.net/services https://api.archivesportaleurope.net/services]
+
In the current version (v5.0.0), sixteen services are available. The endpoint of the API is [https://www.archivesportaleurope.net/ApeApi/ https://api.archivesportaleurope.net/services].
−
 
+
You must use an [[APE_API_documentation#API_Key | API-Key]] and a [[APE_API_documentation#Versioning | special value for accept]] in the HTTP-header.
−
Via [https://www.archivesportaleurope.net/ApeApi/#!/search/search https://www.archivesportaleurope.net/ApeApi/#!/search/search] you can access the ApeApi Explorer were you can try the services and see the responses.
+
 +
Via [https://www.archivesportaleurope.net/ApeApi/ https://www.archivesportaleurope.net/ApeApi/] you can access the ApeApi Explorer were you can try the services and see the responses.
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 18: Line 19:
 
! style="width: 250px;" | EAC-CPF
 
! style="width: 250px;" | EAC-CPF
 
|-
 
|-
−
| style="vertical-align: top" | search (POST)
+
| style="vertical-align: top" | search (POST /GET)
 
| style="vertical-align: top" | Services for searching with a term in the content and filtering on facets
 
| style="vertical-align: top" | Services for searching with a term in the content and filtering on facets
 
| style="vertical-align: top" |
 
| style="vertical-align: top" |
 
* [[searchEad | /search/ead]]
 
* [[searchEad | /search/ead]]
−
<!-- * /search/ead/docList -->
+
* [[searchEadDoclist | /search/ead/docList]]
−
<!-- * /search/ead/descendants -->
+
* [[searchEadDescendants | /search/ead/{id}/descendants]]
−
<!-- * /search/ead/children -->
+
* [[searchEadChildren | /search/ead/{id}/children]]
 +
* [[searchEadDescendantsWithAncestors | /search/ead/{id}/descendantsWithAncestors]]
 +
* [[searchEadFindingAidNo | /search/ead/FindingAidNo]]
 
| style="vertical-align: top" |
 
| style="vertical-align: top" |
 
* [[searchEac | /search/eac-cpf]]
 
* [[searchEac | /search/eac-cpf]]
Line 32: Line 35:
 
| style="vertical-align: top" |
 
| style="vertical-align: top" |
 
* [[contentEadArchdesc | /content/ead/archdesc/{id}]]
 
* [[contentEadArchdesc | /content/ead/archdesc/{id}]]
−
<!-- * /content/ead/archdesc/{id}/children -->
 
 
* [[contentEadClevel | /content/ead/clevel/{id}]]
 
* [[contentEadClevel | /content/ead/clevel/{id}]]
−
<!-- * /content/ead/clevel/{id}/children -->
 
−
<!-- * /content/ead/clevel/{id}/parent -->
 
 
| style="vertical-align: top" |
 
| style="vertical-align: top" |
 
* [[contentEac-cpf | /content/eac-cpf/{id} ]]
 
* [[contentEac-cpf | /content/eac-cpf/{id} ]]
 +
|-
 +
| style="vertical-align: top" | hierarchy (GET)
 +
| style="vertical-align: top" | Services for getting detailed information about the position of a result in the hierarchy of a finding aid
 +
| style="vertical-align: top" |
 +
* [[hierarchyEadChildren | /hierarchy/ead/{id}/children]]
 +
* [[hierarchyEadAncestors | /hierarchy/ead/{id}/ancestors]]
 +
| style="vertical-align: top" |
 
|-
 
|-
 
| style="vertical-align: top" | download (GET)
 
| style="vertical-align: top" | download (GET)
Line 55: Line 62:
 
* [[getDocs | /institute/getDocs]]
 
* [[getDocs | /institute/getDocs]]
 
|}
 
|}
 +
<br/>
 +
 +
= Last additions/changes =
 +
== Version 5.0.0 ==
 +
20170830: currently the production server holds version 5.0.0 of the API, compared to version 4.0.0 two more services have been added:
 +
* [[searchEadDescendantsWithAncestors | /search/ead/{id}/descendantsWithAncestors]]
 +
* [[searchEadFindingAidNo | /search/ead/FindingAidNo]]
 +
<br/>
 +
and the following services have been improved:
 +
<br/>
 +
* [[searchEad | /search/ead]]:
 +
** added the following field to the response: parentId
 +
** in the response: changed the name of the field: "fondsUnitTitle" into: "findingAidTitle" and the field "fondsUnitId" into: "findingAidNo"
 +
* [[searchEadDoclist | /search/ead/docList]]:
 +
** in the response: changed the name of the field: "fondsUnitTitle" into: "findingAidTitle" and the field "fondsUnitId" into: "findingAidNo"
 +
* [[searchEadDescendants | /search/ead/{id}/descendants]]:
 +
** added the following to the request: filters and sortRequest
 +
** added the following field to the response: parentId
 +
** in the response: changed the name of the field: "fondsUnitTitle" into: "findingAidTitle" and the field "fondsUnitId" into: "findingAidNo"
 +
** added the following to the request: filtering (facetting) and sort options
 +
* [[searchEadChildren | /search/ead/{id}/children]]:
 +
** added the following field to the response: parentId
 +
** in the response: changed the name of the field: "fondsUnitTitle" into: "findingAidTitle" and the field "fondsUnitId" into: "findingAidNo"
 +
* [[contentEadArchdesc | /content/ead/archdesc/{id}]]
 +
** in the response: changed the name of the field: "fondsUnitTitle" into: "findingAidTitle" and the field "fondsUnitId" into: "findingAidNo"
 +
* [[contentEadClevel | /content/ead/clevel/{id}]]
 +
** in the response: changed the name of the field: "fondsUnitTitle" into: "findingAidTitle"
 +
* [[hierarchyEadChildren | /hierarchy/ead/{id}/children]]:
 +
** in the response: changed the name of the field: "fondsUnitTitle" into: "findingAidTitle" and the field "fondsUnitId" into: "findingAidNo"
 +
* [[hierarchyEadAncestors | /hierarchy/ead/{id}/ancestors]]:
 +
** in the response: changed the name of the field: "fondsUnitTitle" into: "findingAidTitle" and the field "fondsUnitId" into: "findingAidNo"
 +
* [[getDocs | /institute/getDocs]]:
 +
** added the following to the request: sortRequest
 +
** in the response: changed the name of the field: "fondsUnitTitle" into: "findingAidTitle" and the field "fondsUnitId" into: "findingAidNo"
 +
<br/>
 +
 +
= Previous additions/changes =
 +
== Version 4.0.0 ==
 +
20170531: currently the production server holds version 4.0.0 of the API, compared to version 3.0.0 these services have been improved:
 +
 +
* [[searchEad | /search/ead]]:
 +
** added the following fields to the response:
 +
*** numberOfDigitalObjects
 +
*** numberOfDigitalObjectsInDescendents
 +
*** numberOfDescendents
 +
*** numberOfAncestors
 +
 +
* [[searchEadDoclist | /search/ead/docList]]:
 +
** added the following fields to the response:
 +
*** fondsUnitId
 +
*** unitDate
 +
*** scopeContent
 +
*** numberOfDigitalObjects
 +
*** numberOfDigitalObjectsInDescendents
 +
*** numberOfDescendents
 +
** added facetDateFields (fromDate and toDate) to the response
 +
 +
* [[searchEadDescendants | /search/ead/{id}/descendants]]:
 +
** added the following fields to the response:
 +
*** numberOfDigitalObjects
 +
*** numberOfDigitalObjectsInDescendents
 +
*** numberOfDescendents
 +
*** numberOfAncestors
 +
 +
* [[searchEadChildren | /search/ead/{id}/children]]:
 +
** added the following fields to the response:
 +
*** numberOfDigitalObjects
 +
*** numberOfDigitalObjectsInDescendents
 +
*** numberOfDescendents
 +
*** numberOfAncestors
 +
 +
* [[hierarchyEadChildren | /hierarchy/ead/{id}/children]]:
 +
** added the following fields to the response:
 +
*** numberOfDigitalObjects
 +
*** numberOfDigitalObjectsInDescendents
 +
*** numberOfDescendents
 +
** in the response: changed the name of the field "treeDepth" into: "ancestorLevel"
 +
 +
* [[hierarchyEadAncestors | /hierarchy/ead/{id}/ancestors]]:
 +
** added the following fields to the response:
 +
*** numberOfDigitalObjects
 +
*** numberOfDigitalObjectsInDescendents
 +
*** numberOfDescendents
 +
** in the response: changed the name of the field "treeDepth" into: "ancestorLevel"
 +
 +
* [[getInstitutes | /institute/getInstitutes/{startIndex}/{count}]]:
 +
** in the response: changed the name of the field "numberOfFindingAids" into: "totalDocs"
 +
 +
* [[getDocs | /institute/getDocs]]:
 +
** added the following fields to the response:
 +
*** numberOfDigitalObjects
 +
*** numberOfDigitalObjectsInDescendents
 +
*** numberOfDescendents
 +
 +
== Version 3.0.0 ==
 +
20161101: currently the production server holds version 3.0.0 of the API, compared to version 2.0.0 these services/improvements have been added:
 +
 +
* /search/ead/docList
 +
* /search/ead/{id}/descendants
 +
* /search/ead/{id}/children
  
 +
* /hierarchy/ead/{id}/children
 +
* /hierarchy/ead/{id}/ancestors
  
−
= Future work =
+
added request or response parameters:
−
In the current second version the service of searching and retrieving of archival descriptions as provided in the first version has been expanded with more options for detailed viewing of a finding aid as well as searching and retrieving of archive records creators. This new version also offers the possibility to get a list of all archival institutions that have enabled their data-sets for the API, to get a list of available finding aids per institution and the possibility to download these finding aids as raw data (EAD/XML format). We plan to expand these services any further in the near future with more detailed views on archival records and records creators.
+
  
 +
* /search/ead -> added request parameter sortFields
 +
* /content/ead/clevel -> added response parameter fondsUnitTitle
 +
<br/>
  
 
= API Key =
 
= API Key =
Line 75: Line 186:
  
 
= Versioning =
 
= 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 2.0.0 this is: application/vnd.ape-v2+json
+
Depending on the version of the API that you want to use, the Content-Type parameter in the header must be set to a specific Content Type. For version 5.0.0 this is: application/vnd.ape-v5+json
  
 
eg.  
 
eg.  
 
<pre>
 
<pre>
−
  'accept' : 'application/vnd.ape-v2+json'
+
  'Content-Type' : 'application/vnd.ape-v5+json'
 
</pre>
 
</pre>
  
 
[[Category:Technical_documentation]]
 
[[Category:Technical_documentation]]

Latest revision as of 09:13, 24 November 2017

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 (v5.0.0), sixteen services are available. The endpoint of the API is https://api.archivesportaleurope.net/services. You must use an API-Key and a special value for accept in the HTTP-header.

Via https://www.archivesportaleurope.net/ApeApi/ you can access the ApeApi Explorer were you can try the services and see the responses.

Description EAD EAC-CPF
search (POST /GET) Services for searching with a term in the content and filtering on facets
content (GET) Services for getting detailed information about a particular result
hierarchy (GET) Services for getting detailed information about the position of a result in the hierarchy of a finding aid
download (GET) Services for downloading XML-files
institute (POST / GET) Services for getting full lists


Last additions/changes

Version 5.0.0

20170830: currently the production server holds version 5.0.0 of the API, compared to version 4.0.0 two more services have been added:


and the following services have been improved:

  • /search/ead:
    • added the following field to the response: parentId
    • in the response: changed the name of the field: "fondsUnitTitle" into: "findingAidTitle" and the field "fondsUnitId" into: "findingAidNo"
  • /search/ead/docList:
    • in the response: changed the name of the field: "fondsUnitTitle" into: "findingAidTitle" and the field "fondsUnitId" into: "findingAidNo"
  • /search/ead/{id}/descendants:
    • added the following to the request: filters and sortRequest
    • added the following field to the response: parentId
    • in the response: changed the name of the field: "fondsUnitTitle" into: "findingAidTitle" and the field "fondsUnitId" into: "findingAidNo"
    • added the following to the request: filtering (facetting) and sort options
  • /search/ead/{id}/children:
    • added the following field to the response: parentId
    • in the response: changed the name of the field: "fondsUnitTitle" into: "findingAidTitle" and the field "fondsUnitId" into: "findingAidNo"
  • /content/ead/archdesc/{id}
    • in the response: changed the name of the field: "fondsUnitTitle" into: "findingAidTitle" and the field "fondsUnitId" into: "findingAidNo"
  • /content/ead/clevel/{id}
    • in the response: changed the name of the field: "fondsUnitTitle" into: "findingAidTitle"
  • /hierarchy/ead/{id}/children:
    • in the response: changed the name of the field: "fondsUnitTitle" into: "findingAidTitle" and the field "fondsUnitId" into: "findingAidNo"
  • /hierarchy/ead/{id}/ancestors:
    • in the response: changed the name of the field: "fondsUnitTitle" into: "findingAidTitle" and the field "fondsUnitId" into: "findingAidNo"
  • /institute/getDocs:
    • added the following to the request: sortRequest
    • in the response: changed the name of the field: "fondsUnitTitle" into: "findingAidTitle" and the field "fondsUnitId" into: "findingAidNo"


Previous additions/changes

Version 4.0.0

20170531: currently the production server holds version 4.0.0 of the API, compared to version 3.0.0 these services have been improved:

  • /search/ead:
    • added the following fields to the response:
      • numberOfDigitalObjects
      • numberOfDigitalObjectsInDescendents
      • numberOfDescendents
      • numberOfAncestors
  • /search/ead/docList:
    • added the following fields to the response:
      • fondsUnitId
      • unitDate
      • scopeContent
      • numberOfDigitalObjects
      • numberOfDigitalObjectsInDescendents
      • numberOfDescendents
    • added facetDateFields (fromDate and toDate) to the response
  • /search/ead/{id}/descendants:
    • added the following fields to the response:
      • numberOfDigitalObjects
      • numberOfDigitalObjectsInDescendents
      • numberOfDescendents
      • numberOfAncestors
  • /search/ead/{id}/children:
    • added the following fields to the response:
      • numberOfDigitalObjects
      • numberOfDigitalObjectsInDescendents
      • numberOfDescendents
      • numberOfAncestors
  • /hierarchy/ead/{id}/children:
    • added the following fields to the response:
      • numberOfDigitalObjects
      • numberOfDigitalObjectsInDescendents
      • numberOfDescendents
    • in the response: changed the name of the field "treeDepth" into: "ancestorLevel"
  • /hierarchy/ead/{id}/ancestors:
    • added the following fields to the response:
      • numberOfDigitalObjects
      • numberOfDigitalObjectsInDescendents
      • numberOfDescendents
    • in the response: changed the name of the field "treeDepth" into: "ancestorLevel"
  • /institute/getDocs:
    • added the following fields to the response:
      • numberOfDigitalObjects
      • numberOfDigitalObjectsInDescendents
      • numberOfDescendents

Version 3.0.0

20161101: currently the production server holds version 3.0.0 of the API, compared to version 2.0.0 these services/improvements have been added:

  • /search/ead/docList
  • /search/ead/{id}/descendants
  • /search/ead/{id}/children
  • /hierarchy/ead/{id}/children
  • /hierarchy/ead/{id}/ancestors

added request or response parameters:

  • /search/ead -> added request parameter sortFields
  • /content/ead/clevel -> added response parameter fondsUnitTitle


API Key

To enable the Archives Portal Europe team 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 on the homepage of the portal, or directly via this url: https://www.archivesportaleurope.net/get-api-key.

Note: you need to be a registered user of the Archives Portal Europe to be able to get an API key, so if you don't have an account for the Archives Portal Europe's My Pages functionality yet, please create one first. You can read more on the My Pages functionality over here.

Using the API 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 Content-Type parameter in the header must be set to a specific Content Type. For version 5.0.0 this is: application/vnd.ape-v5+json

eg. 

 	'Content-Type' : 'application/vnd.ape-v5+json'
Retrieved from "http://wiki-deprecated.archivesportaleurope.net/index.php?title=APE_API_documentation&oldid=1738"