...

Note

title	Here are some technical essentials to start using the API

The base URL for the API is cloud.europeana.eu/api https://ecloud.psnc.pl/
To use the API one needs you will need a user account. Obtain one from the Europeana Cloud team.
The part of the Tutorial below gives examples and 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.
You might be interested in a Java client libraries - there are available in Europeana Cloud source code repository.
In the examples below user credentials are provided using the --user parameter

...

Code Block

language	bash

curl -X POST -H "Content-Type: application/json" --user user:password -d '{
    "organisationWebsiteURL": "http://www.man.poznan.pl",
    "organisationWebsite": "Poznańskie Centrum Superkomputerowo - Sieciowe Afiliowane przy Instytucie Chemii Bioorganicznej PANPoznan Supercomputing and Networking Center Affiliated to Institute of Bioorganic Chemistry Polish Academy of Science",
    "officialAddress" : "ul. Jana Pawła II 10, Poznań",
    "digitalLibraryURL" : "http://lib.psnc.pl/dlibra",
    "digitalLibraryWebsite": "RepozytoriumInstitutional InstytucjonalneRepository",
    "organisationName": "PoznańskiePoznan CentrumSupercomputing Superkomputerowoand -Networking SiecioweCenter AfiliowaneAffiliated przy Instytucie Chemii Bioorganicznej PANto Institute of Bioorganic Chemistry Polish Academy of Science",
    "remarks": "Integracja i rozwój infrastruktury informatycznej naukiIntegrating and developing the information infrastructure for science",
    "contactPerson": "office@man.poznan.pl"
}' -i https://cloudecloud.europeanapsnc.eupl/api/data-providers?providerId=PSNC

...

Code Block

language	bash

 curl -X GET  -H "Accept: application/json" --user user:password -i https://cloudecloud.europeanapsnc.eupl/api/data-providers/PSNC

The response should look like this:

Code Block

language	bash

 {  
   "active":true,
   "id":"PSNC",
   "partitionKey":2465528,
   "properties":{  
      "contactPerson":"office@man.poznan.pl",
      "digitalLibraryURL":"http://lib.psnc.pl/dlibra",
      "digitalLibraryWebsite":"RepozytoriumInstitutional InstytucjonalneRepository",
      "officialAddress":"ul. Jana Pawła II 10, Poznań",
      "organisationName":"PoznańskiePoznan CentrumSupercomputing Superkomputerowoand -Networking SiecioweCenter AfiliowaneAffiliated przyto InstytucieInstitute Chemii Bioorganicznej PANof Bioorganic Chemistry Polish Academy of Science",
      "organisationWebsite":"Poznańskie Centrum Superkomputerowo - Sieciowe Afiliowane przy Instytucie Chemii Bioorganicznej PANPoznan Supercomputing and Networking Center Affiliated to Institute of Bioorganic Chemistry Polish Academy of Science",
      "organisationWebsiteURL":"http://www.man.poznan.pl",
      "remarks":"Integracja i rozwój infrastruktury informatycznej naukiIntegrating and developing the information infrastructure for science"
   }
}

Identifiers

Creation

...

Code Block

language	bash

curl -X POST --user user:password -i https://cloudecloud.europeanapsnc.eupl/api/cloudIds?providerId=PSNC\&recordId=exampleLocalRecord

Note
Have you noticed the "\&" before recordId parameter? the & character had to be escaped because it is a special character in bash. You might not need it if you use another interpreter or HTTP client.

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

...

Code Block
curl -X POST --user user:password https://cloudecloud.europeanapsnc.eupl/api/cloudIds?providerId=exampleProvider

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

...

Code Block
curl -X GET -H "Accept: application/json" --user user:password -i https://cloudecloud.europeanapsnc.eupl/api/data-providers/PSNC/cloudIds

...

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:

Code Block

curl -X POST -H "Accept: application/json" --user user:password -H "Content-Type: application/x-www-form-urlencoded" -d 'providerId=PSNC' -i https://cloudecloud.europeanapsnc.eupl/api/records/X67WPA7NGCZUKLACPWU3BORRGQUWTKSZNZDICEGZS6IXTRMINOIQ/representations/TIFF

curl -X POST -H "Accept: application/json" --user user:password -H "Content-Type: application/x-www-form-urlencoded" -d 'providerId=PSNC' -i https://cloudecloud.europeanapsnc.eupl/api/records/X67WPA7NGCZUKLACPWU3BORRGQUWTKSZNZDICEGZS6IXTRMINOIQ/representations/thumbnail

curl -X POST -H "Accept: application/json" --user user:password -H "Content-Type: application/x-www-form-urlencoded" -d 'providerId=PSNC' -i https://cloudecloud.europeanapsnc.eupl/api/records/X67WPA7NGCZUKLACPWU3BORRGQUWTKSZNZDICEGZS6IXTRMINOIQ/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:

Code Block
https://cloudecloud.europeanapsnc.eupl/api/records/X67WPA7NGCZUKLACPWU3BORRGQUWTKSZNZDICEGZS6IXTRMINOIQ/representations/thumbnail/versions/cd9f0050-3dea-11e6-b03d-fa163e8d4ae3

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

...

Code Block

curl -X POST --user user:password -H "Content-Type: multipart/form-data" -F "mimeType=application/png" -F "data=@thumbnail.png" https://cloudecloud.europeanapsnc.eupl/api/records/X67WPA7NGCZUKLACPWU3BORRGQUWTKSZNZDICEGZS6IXTRMINOIQ/representations/thumbnail/versions/cd9f0050-3dea-11e6-b03d-fa163e8d4ae3/files

...

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

Code Block

https://cloudecloud.europeanapsnc.eupl/api/records/X67WPA7NGCZUKLACPWU3BORRGQUWTKSZNZDICEGZS6IXTRMINOIQ/representations/thumbnail/versions/cd9f0050-3dea-11e6-b03d-fa163e8d4ae3/files/1df7a491-8d8a-4180-9eb0-cd18c52a4b81

...

Code Block

curl -X POST --user user:password -i https://cloudecloud.europeanapsnc.eupl/api/records/X67WPA7NGCZUKLACPWU3BORRGQUWTKSZNZDICEGZS6IXTRMINOIQ/representations/thumbnail/versions/cd9f0050-3dea-11e6-b03d-fa163e8d4ae3/persist

...

Code Block

curl -X DELETE --user user:password https://cloudecloud.europeanapsnc.eupl/api/records/X67WPA7NGCZUKLACPWU3BORRGQUWTKSZNZDICEGZS6IXTRMINOIQ/representations/thumbnail/versions/cd9f0050-3dea-11e6-b03d-fa163e8d4ae3/

...

Code Block
curl -X POST --user user:password -H "Content-Type: application/x-www-form-urlencoded" -d 'dataSetId=exampleDataSet' -i https://cloudecloud.europeanapsnc.eupl/api/data-providers/PSNC/data-sets

...

Code Block

curl -X POST --user user:password -H "Content-Type: application/x-www-form-urlencoded" -d 'cloudId=X67WPA7NGCZUKLACPWU3BORRGQUWTKSZNZDICEGZS6IXTRMINOIQ&representationName=thumbnail&version=cd9f0050-3dea-11e6-b03d-fa163e8d4ae3' -i https://cloudecloud.europeanapsnc.eupl/api/data-providers/PSNC/data-sets/exampleDataSet/assignments

...

Code Block

curl -X DELETE --user user:password -H "Content-Type: application/x-www-form-urlencoded" -i https://cloudecloud.europeanapsnc.eupl/api/data-providers/PSNC/data-sets/exampleDataSet/assignments?cloudId=X67WPA7NGCZUKLACPWU3BORRGQUWTKSZNZDICEGZS6IXTRMINOIQ\&representationName=thumbnail

...

Code Block
curl -X GET -H "Accept: application/xml" --user user:password -i https://cloudecloud.europeanapsnc.eupl/api/data-providers/PSNC/data-sets/exampleDataSet/

...

Code Block
curl -X DELETE -H "Accept: application/json" --user user:password -i https://cloudecloud.europeanapsnc.eupl/api/data-providers/PSNC/data-sets/exampleDataSet/

...

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

...

Code Block

curl -X POST --user user:password -i https://cloudecloud.europeanapsnc.eupl/api/records/X67WPA7NGCZUKLACPWU3BORRGQUWTKSZNZDICEGZS6IXTRMINOIQ/representations/thumbnail/versions/cd9f0050-3dea-11e6-b03d-fa163e8d4ae3/permit

...

Code Block

curl -X POST --user user:password https://cloudecloud.europeanapsnc.eupl/api/records/X67WPA7NGCZUKLACPWU3BORRGQUWTKSZNZDICEGZS6IXTRMINOIQ/representations/thumbnail/versions/cd9f0050-3dea-11e6-b03d-fa163e8d4ae3/permissions/permission/users/anotherUser

...

Friendly URLs

Sometimes it is hard for a client to get the global identifier of a record, generated version name of a representation and generated filename. On the other hand the client has got a local record identifier which is well known. The same may be in case of a filename. In order to access files without retrieving the hard to remember identifiers and names mechanism of friendly URLs was introduced. The idea behind it is to use in URLs well known values (identifiers, names, etc.) always in the same way. Here we will go through the tutorial steps using friendly URLs where it is possible.

Record

Normally when you know the cloud identifier of a record you can access it using URL like this:

Code Block
https://cloudecloud.europeanapsnc.eupl/api/records/X67WPA7NGCZUKLACPWU3BORRGQUWTKSZNZDICEGZS6IXTRMINOIQ

If you remember from the beginning of this tutorial, this record was created for PSNC data provider together with local identifier which was exampleLocalRecord. So now we have only two values: name of the data provider (PSNC) and identifier used by this data provider (exampleLocalRecord). To get access to this record in Europeana Cloud using just these two values we can use friendly URL like this:

Code Block
curl -X GET -H "Accept: application/json" --user user:password -i https://cloudecloud.europeanapsnc.eupl/api/data-providers/PSNC/records/exampleLocalRecord

Representation

Sometimes it is necessary to get access to a specific representation. Again, instead of retrieving the global identifier we can use well known values like data provider name, local record identifier and representation name. Let's display information about the TIFFrepresentation using the friendly URL:

Code Block
curl -X GET -H "Accept: application/json" --user user:password -i https://cloudecloud.europeanapsnc.eupl/api/data-providers/PSNC/records/exampleLocalRecord/representations/TIFF

File

If you do not want to have files with names generated by the system there is possibility to specify the name in the insert request. We can add a file to TIFF representation and specify a name for it like this:

Code Block

curl -X POST --user user:password -H "Content-Type: multipart/form-data" -F "mimeType=image/tiff" -F "data=@tiff.tiff" -F "fileName=abc" https://cloudecloud.europeanapsnc.eupl/api/records/X67WPA7NGCZUKLACPWU3BORRGQUWTKSZNZDICEGZS6IXTRMINOIQ/representations/TIFF/versions/27ae2a60-3ebf-11e6-b03d-fa163e8d4ae3/files

As you can see the specified filename is abc. Now we can use it to access this file in Europeana Cloud via friendly URL.

Note
Just remember that a file will not be accessible until you make its representation persistent.

Code Block
curl -X GET -H "Accept: application/json" --user user:password -i https://cloudecloud.europeanapsnc.eupl/api/data-providers/PSNC/records/exampleLocalRecord/representations/TIFF/abc

Filename used instead of a generated one can be also much more complex. It can for example contain / characters like in the absolute path. We can take a look at the real example provided by Europeana Newspapers.

Code Block

https://cloudecloud.europeanapsnc.eupl/api/data-providers/TheEuropeanLibrary/records/3000100349685/representations/presentation_images/node-2/image/NLE/???????????_??????????_?????????_=_Livländische_Gouvernements-Zeitung/1862/01/03/18620103_1-0001.jp2

As you can see the filename used here (node-2/image/NLE/???????????_??????????_?????????_=_Livländische_Gouvernements-Zeitung/1862/01/03/18620103_1-0001.jp2) is not only long with , having / characters inside but also contains unicode characters. We can also extract other well known values from this URL: data provider - TheEuropeanLibrary, local record identifier - 3000100349685, representation name - presentation_images.

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.

...

.

Page tree

Versions Compared

Old Version 23

New Version Current

Key

Identifiers

Creation

Representations

Friendly URLs

Record

Representation

File

Future Work and Contact

Page tree

Page History

Versions Compared

Old Version 23

New Version Current

Key

Identifiers

Creation

Representations

Friendly URLs

Record

Representation

File

Future Work and Contact