Difference between revisions of "APE API documentation"
| Line 8: | Line 8: | ||
<div><br/>__TOC__<br/></div> | <div><br/>__TOC__<br/></div> | ||
= The services = | = The services = | ||
| − | In the current version ( | + | In the current version (v3.0.0), various services are available. The endpoint of the API is [https://api.archivesportaleurope.net/services https://api.archivesportaleurope.net/services] |
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/#!/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. | ||
| Line 22: | Line 22: | ||
| style="vertical-align: top" | | | style="vertical-align: top" | | ||
* [[searchEad | /search/ead]] | * [[searchEad | /search/ead]] | ||
| − | + | * [[searchEadDoclist | /search/ead/docList]] | |
| − | + | * [[searchEadDescendants | /search/ead/{id}/descendants]] | |
| − | + | * [[searchEadChildren | /search/ead/{id}/children]] | |
| style="vertical-align: top" | | | style="vertical-align: top" | | ||
* [[searchEac | /search/eac-cpf]] | * [[searchEac | /search/eac-cpf]] | ||
| Line 32: | Line 32: | ||
| style="vertical-align: top" | | | style="vertical-align: top" | | ||
* [[contentEadArchdesc | /content/ead/archdesc/{id}]] | * [[contentEadArchdesc | /content/ead/archdesc/{id}]] | ||
| − | |||
* [[contentEadClevel | /content/ead/clevel/{id}]] | * [[contentEadClevel | /content/ead/clevel/{id}]] | ||
| − | |||
| − | |||
| 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 59: | ||
* [[getDocs | /institute/getDocs]] | * [[getDocs | /institute/getDocs]] | ||
|} | |} | ||
| + | <br/> | ||
| + | = Last additions = | ||
| + | 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 | ||
| + | <br/> | ||
= API Key = | = 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 [https://www.archivesportaleurope.net/information-api API] on the homepage of the portal, or directly via this url: [https://www.archivesportaleurope.net/get-api-key https://www.archivesportaleurope.net/get-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 [https://www.archivesportaleurope.net/information-api API] on the homepage of the portal, or directly via this url: [https://www.archivesportaleurope.net/get-api-key https://www.archivesportaleurope.net/get-api-key]. | ||
| Line 75: | Line 89: | ||
= 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 | + | 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 3.0.0 this is: application/vnd.ape-v3+json |
eg. | eg. | ||
<pre> | <pre> | ||
| − | 'accept' : 'application/vnd.ape- | + | 'accept' : 'application/vnd.ape-v3+json' |
</pre> | </pre> | ||
[[Category:Technical_documentation]] | [[Category:Technical_documentation]] | ||
Revision as of 08:18, 1 November 2016
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 (v3.0.0), various services are available. The endpoint of the API is https://api.archivesportaleurope.net/services
Via https://www.archivesportaleurope.net/ApeApi/#!/search/search you can access the ApeApi Explorer were you can try the services and see the responses.
| Description | EAD | EAC-CPF | |
|---|---|---|---|
| search (POST) | 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
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 accept parameter in the header must be set to a specific Content Type. For version 3.0.0 this is: application/vnd.ape-v3+json
eg.
'accept' : 'application/vnd.ape-v3+json'
