You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Using the API

Here are some technical essentials to start using the API:

    • The base URL for the API is cloud.europeana.eu/api

    • To use the API one needs a user. Obtain one from the Europeana Cloud team.

    • The part of the Tutorial below gives examples and demonstrates demonstrates the API calls using the popular command line utility cURL for submitting HTTP requests. One can use other tools to submit HTTP requests if desired.

    • In the future we'll also provide convenient client-side libraries in popular languages, such as Java.

    • In the examples below user credentials are provided using the --user parameter

Data Providers

Each piece of data uploaded to Europeana Cloud is to be owned by a data provider. You can manage the data providers - create or update them - using the API. Let's start with creating one. This is done using the /data-providers method.

Creation

You need to provide an unique identifier for the provider in the providerId parameter. You can specify additional properties and send them as JSON in data block:

curl -X POST -H "Content-Type: application/json" --user user:password -d '{
 "organisationWebsiteURL": "example.com",
 "officialAddress" : "address@example.com",
 "digitalLibraryURL" : "example.com/library",
 "organisationName": "Example",
 "remarks": "example remarks",
 "contactPerson": "John example"
}' -i https://cloud.europeana.eu/api/data-providers?providerId=exampleProvider

If the provider was created successfully you will get a response with HTTP code 200. You can use the GET method on the same endpoint to make sure that the system returns information about the data provider, when queried by its id:

curl -X GET  -H "Accept: application/json" --user user:password -i https://cloud.europeana.eu/api/data-providers/exampleProvider

The response should look like this:

{
    "id":"exampleProvider",
    "partitionKey":-1322970774,
    "properties":
    {
        "contactPerson":"John example",
        "digitalLibraryURL":"example.com/library",
        "officialAddress":"address@example.com",
        "organisationName":"Example",
        "organisationWebsiteURL":"example.com",
        "remarks":"example remarks"
    }
}

Identifiers

Creation

Every record has a unique identifier in Europeana Cloud. We call these identifiers "global". A record can also have an identifier in its original the system; these ïdentifiers are referred to as “local”.

Prior to uploading data to a record, the system needs to generate its global identifier and map it to the local one.

curl -X POST --user user:password -i https://cloud.europeana.eu/api/cloudIds?providerId=exampleProvider\&recordId=exampleLocalRecord

The response will contain the mapping between the local record and the newly created identifier LE27IU4ZYQP4OQU2EJLCT2LSSDZO2YVIJYX27JWT4RN7PQNF76IA:

{   
   "id": "LE27IU4ZYQP4OQU2EJLCT2LSSDZO2YVIJYX27JWT4RN7PQNF76IA",
   "localId": {
      "providerId": "exampleProvider",
      "recordId": "exampleLocalRecord"
   }
}

You can also choose not to provide a local identifier if it will not be used

curl -X POST --user user:password https://cloud.europeana.eu/api/cloudIds?providerId=exampleProvider

The newly created global identifier and a local one can be found in the response:

 { 
"id": "NFKFJROBL4B7V6VGBE4LBTHPRLXSKLCBLCZYAEHCLA7VZ3FWAKJQ",
   "localId": {
      "providerId": "exampleProvider",
      "recordId": "TYAGJAWWDALPUXUUTTXBSZ26VSZRMWJ5RBOFK5KOGOBT35AN5HOQ"
   }
}

Listing

You can browse all the global ids associated with a specific data provider using the /cloudIdsREST endpoint:

curl -X GET  -H "Accept: application/json" --user user:password -i https://cloud.europeana.eu/api/data-providers/exampleProvider/cloudIds

In the response we should get a list of all cloud identifiers assigned to our provider.

{

  "results": [

   {

     "type": "cloudId",

     "id": "NFKFJROBL4B7V6VGBE4LBTHPRLXSKLCBLCZYAEHCLA7VZ3FWAKJQ",

     "localId": {

       "providerId": "exampleProvider",

       "recordId": "TYAGJAWWDALPUXUUTTXBSZ26VSZRMWJ5RBOFK5KOGOBT35AN5HOQ"

     }

   },

   {

     "type": "cloudId",

     "id": "LE27IU4ZYQP4OQU2EJLCT2LSSDZO2YVIJYX27JWT4RN7PQNF76IA",

     "localId": {

       "providerId": "exampleProvider",

       "recordId": "exampleLocalRecord"

     }

   }

 ]

}

Now you are ready to fill Europeana Cloud with some data.

Records, Representations and Files

A record is the central entity of the storage system. It has a global identifier and and consists of several representations.

Representations

Lets get back to our example in the Data Model section. Say that you want to create a record out of the three files you have. Each one will be stored in a different representation. Creating new representations is done using the /records REST endpoint:

curl -X POST "Accept: application/json" --user user:password -H "Content-Type: application/x-www-form-urlencoded" -d 'providerId=exampleProvider'  https://cloud.europeana.eu/api/records/9H9WXX872WL/representations/TIFF
curl -X POST "Accept: application/json" --user user:password -H "Content-Type: application/x-www-form-urlencoded" -d 'providerId=exampleProvider'  https://cloud.europeana.eu/api/records/9H9WXX872WL/representations/thumbnail
curl -X POST "Accept: application/json" --user user:password -H "Content-Type: application/x-www-form-urlencoded" -d 'providerId=exampleProvider'  https://cloud.europeana.eu/api/records/9H9WXX872WL/representations/EDM

When successful, the response will have HTTP status code 201 (Created). Note that when a new representation is created, it is automatically assigned a new version. This new version can be reached directly using a URL which is returned in the location field of the response header. The URL will be of the following format:

https://cloud.europeana.eu/api/records/9H9WXX872WL/representations/thumbnail/versions/6ab713f0-bcf5-11e4-919c-525400ea6731

Subsequent versions of a representation can be created further in the future, for example to reflect ongoing work on a file.

Files and Versions

You just created metadata entries for your data representations. Now it’s time to attach real data to them. For this the /versions REST endpoint is used. For example, to add a thumbnail file to a previously created representation thumbnail:

curl -X POST --user user:password -H "Content-Type: multipart/form-data" -F "mimeType=application/png" -F "data=@thumbnail.png" https://cloud.europeana.eu/api/records/9H9WXX872WL/representations/thumbnail/versions/6ab713f0-bcf5-11e4-919c-525400ea6731/files

URI of the newly added file will be returned in the location field of the response header:

https://cloud.europeana.eu/api/records/9H9WXX872WL/representations/thumbnail/versions/6ab713f0-bcf5-11e4-919c-525400ea6731/files/141bf166-532d-4ebb-8a41-c4db22ed4925

You can add multiple files to a version.

The newly created version is a temporary one, which means it can be removed. To make a version persistent, you can use the /persist call:

curl -X POST --user user:password  https://cloud.europeana.eu/api/records/9H9WXX872WL/representations/TIFF/versions/32233f0-bc333-1e3-919c-52dfgdfdf1/persist

A successful call will return 201 HTTP Code.

Deletion

Versions can be deleted using the DELETE call as follows:

curl -X DELETE --user user:password
https://cloud.europeana.eu/api/records/9H9WXX872WL/representations/thumbnail/versions/6ab713f0-bcf5-11e4-919c-525400ea6731/

You can only delete a temporary version of a representation. If you will try to remove a

persistent version you will get HTTP status code 405 (Not Allowed).

Datasets

Datasets in Europeana Cloud are a way to group records for thematic or operational reasons. One record can belong to many datasets.

Creation

To create a new dataset, use the /dataset call where you specify the name of the dataset.

curl -X POST --user user:password -H "Content-Type: application/x-www-form-urlencoded" -d 'dataSetId=exampleDataSet' https://cloud.europeana.eu/api/data-providers/exampleProvider/data-sets

Modification

Having created one, you can assign your representation versions to this dataset. To do this use the/assignments call providing the global id, the representation name and the version identifier. If you won't pass the version identifier parameter, the latest persistent version will be assigned to data set.

curl -X POST --user user:password -H "Content-Type: application/x-www-form-urlencoded" -d 'cloudId=9H9WXX872WL&representationName=thumbnail&version=6ab713f0-bcf5-11e4-919c-525400ea6731' -i https://cloud.europeana.eu/api/data-providers/exampleProvider/data-sets/exampleDataSet/assignments

To remove a representation version from a dataset, use the /assignments REST method when you specify the dataset and representation URL:

curl -X POST --user user:password -H "Content-Type: application/x-www-form-urlencoded" -d 'cloudId=9H9WXX872WL&representationName=thumbnail&version=6ab713f0-bcf5-11e4-919c-525400ea6731' -i https://cloud.europeana.eu/api/data-providers/exampleProvider/data-sets/exampleDataSet/assignments

Listing

To view the content of a dataset, use the /data-sets REST endpoint when providing the data provider id and the dataset id.

curl -X GET  -H "Accept: application/json" --user user:password -i  https://cloud.europeana.eu/api/data-providers/exampleProvider/data-sets/exampleDataSet/

Deletion

To delete the dataset use the /data-sets REST endpoint when providing the data provider id and the dataset id.

curl -X DELETE -H "Accept: application/json" --user user:password -i  https://cloud.europeana.eu/api/data-providers/exampleProvider/data-sets/exampleDataSet/

Permissions

Permission Granularity

In Europeana Cloud access to data entities is governed by permissions assigned to these entities. The way these permissions represent our policies on access and rights will be based on the general principles listed in the Europeana Cloud Access Framework.

In the current version access is managed on the level of files. That means that data owners can grant or revoke access to files owned by them. In future versions we will consider extending permission management also to higher levels: representations, records or datasets.

Using Permissions

Taking our example, assume that you want to make your thumbnail files publicly available. For this use the /permit REST call to to change permissions for thumbnail representations of your records.

curl -X POST --user user:password -i https://cloud.europeana.eu/api/records/9H9WXX872WL/representations/thumbnail/versions/6ab713f0-bcf5-11e4-919c-525400ea6731/permit

If you want to give permissions to another user user:

curl -X POST --user user:password https://cloud.europeana.eu/api/records/9H9WXX872WL/representations/thumbnail/versions/6ab713f0-bcf5-11e4-919c-525400ea6731/users/anotherUser/permit/permission

Future Work and Contact

Europeana Cloud is now in its alpha phase. During the remainder of the project we’ll improve the platform and the API based on the feedback from the community.

We welcome your feedback. Please write to pavel.kats at europeana.eu.

  • No labels