Skip to content

Getting Started Guide for Client Developers

Jump to bottom Edit New page
chseifert edited this page Nov 26, 2015 · 5 revisions

Getting Started Guide for Client Developers

If you want to develop a client for the EEXCESS services you will find all information you need to develop your first simple client on this page.

You will learn about the three important ingredients

  • The request format, i.e., how to ask for results from the server.
  • The response format, i.e., how the responses from the server look like.
  • The server endpoint, i.e. whom to talk to when wanting responses.

We will do this in a step by step fashion.

Step-by-Step Tutorial

Step 1: The minimal request

The minimal request only requires a search phrase and the origin of the requesting component, we will use "Douglas Adams" as an example. You could use any values to describe your requesting components, but they should be indicative and describe your component in a sensible way. The json object for the minimal request looks like the following:

{
   "contextKeywords":[
      {
         "text":"Douglas Adams",
      }
   ],
   "origin": {
      "clientType": "My super client", 
      "clientVersion": "0.1",
      "module": "curl command line",
      "userID": "9384324107084"
   }
}

You might want to copy and past this json code and save it as "simple-request.json". Alternatively, you might download simple example json and remove the .txt file ending.

Step 2: Sending the request to the server

An installation of the EEXCESS server components is located at the server

http://eexcess-dev.joanneum.at/

We need to talk to the privacy proxy component, which is reachable via the directory

eexcess-privacy-proxy-issuer-1.0-SNAPSHOT/issuer/

Also, from the privacy proxy component, we need to ask for recommendations, thus the full server endpoint is as follows

https://eexcess-dev.joanneum.at/eexcess-privacy-proxy-issuer-1.0-SNAPSHOT/issuer/recommend

Further, the endpoint uses the HTTP POST method, understands json, and returns json. We need to set this in the header of the request.

With the command line tool CURL, we are now ready to issue our first request:

curl -X POST -d @simple-request.json \
--header "Accept: application/json" --header "Content-Type:application/json" \
https://eexcess-dev.joanneum.at/eexcess-privacy-proxy-issuer-1.0-SNAPSHOT/issuer/recommend

If you have python installed you can get a prettier output when using

curl -X POST -d @simple-request.json \
--header "Accept: application/json" --header "Content-Type:application/json" \
https://eexcess-dev.joanneum.at/eexcess-privacy-proxy-issuer-1.0-SNAPSHOT/issuer/recommend \
| python -mjson.tool

At first the output might look large and messy, have a look a the prettily-printed output of the first response.

Step 3: Understanding the response from the server

For the purpose of this guide, we will not have a look at the full details of the response, just at the parts that are relevant to display a simple result list. To do this, we only need to look at the parts of the sample response that starts with "result". Have a look at a simplified version with two results:

   "result": [
       {
            "date": "1831-01-01",
            "documentBadge": {
                "id": "/2022333/7B368875DFBE1387BE26CBE7F8DDD8B69CB3204F",
                "provider": "Europeana",
                "uri": "http://europeana.eu/resolve/record/2022333/7B368875DFBE1387BE26CBE7F8DDD8B69CB3204F"
            },
            "generatingQuery": "(Douglas AND Adams)",
            "language": "en",
            "licence": "http://www.europeana.eu/rights/rr-r/",
            "mediaType": "TEXT",
            "resultGroup": [],
            "title": "prospects of Britain [electronic resource]"
        },
        {
            "date": "unknown",
            "documentBadge": {
                "id": "U7NMVM4IJDE77EVQN4WTBVRCCVS5THIW",
                "provider": "Deutsche Digitale Bibliothek",
                "uri": "https://www.deutsche-digitale-bibliothek.de/item/U7NMVM4IJDE77EVQN4WTBVRCCVS5THIW"
            },
            "generatingQuery": "Douglas AND Adams",
            "language": "unknown",
            "licence": "https://creativecommons.org/publicdomain/zero/1.0/",
            "mediaType": "unknown",
            "resultGroup": [],
            "title": "Per Anhalter durch die Galaxis - im Licht der Wissenschaft"
        }
]

The first result was provided by Europeana. Attributes that are of interest for a first implementation of a result list are

  • The title of the digital object ("title": "prospects of Britain [electronic resource]")
  • The URI, where the resource can be found ("uri": "http://europeana.eu/resolve/record/2022333)
  • The date, that is assigned to this object. This could either be the data of generation, the date of excavation (of an architectural object) the date, the object was published digitally (in the case of publications for instance). In general the meaning of the date field is not unambiguous, an filling the data correctly on the server-side is ongoing research in the field of meta-data harmonization.
  • The media type. Media types can either be "text", "images", "audio", "video", "3d" (for an example look at this object , which holds a PDF with integrated 3D content ), or "unkown" (if we don't know exactly).

Further Resources

Add a custom footer
Add a custom sidebar

Clone this wiki locally