Test Drive Redlink APIs

David Riccitelli

15.Sep.2013

In this post I’ll guide through a test drive of Redlink’s APIs. By the time you’ll complete these steps, you’ll be able to send textual content to Redlink and receive the list of discovered entities in JSON format.

First of all get your Redlink account by signing up on the Redlink API site. Registration is straight-forward and will require less than a minute.

After login, click on ‘My Applications‘ to create a client app, e.g. “TestApp” (you can leave ‘Callback URL’ empty for the time being):

new-application

 

Click on Add to add the client application, then open the API menu and choose the Redlink API:

apis

 

Then subscribe the client application to the API, choosing whichever tier you prefer:

subscribe-to-api

 

Open the ‘My Subscriptions‘ page, and click on the ‘Generate’ button to generate your access codes:

generate-keys

 

Great, if you reached this point you’re just moment away trying our the Redlink API. For this purpose we’ll use curl on a terminal window.

In order to call the API you’ll need to use the Access Token. Each access token has a validity of 1 hour, therefore you need to use your Consumer Key and Consumer Secret to request an Access Token:

curl -3 -u <consumer-key>:<consumer-secret> 
-d "grant_type=password&username=<username>&password=<password>&scope=PRODUCTION" 
-H "Content-Type: application/x-www-form-urlencoded" 
https://api.redlink.io/api/token

The remote server will reply with a Refresh Token and an Access Token (and its expiration in seconds):

{"token_type":"bearer","expires_in":3600,"refresh_token":"<refresh-token>","access_token":"<access-token>"}

Pay attention to the expiration of the token. In case it is expired, you can request a new one with the above method.

Now create a text file on your computer with some text, e.g. “Redlink can detect famous cities such as Paris and people such as Bob Marley.”, saving the file as payload.txt for example.

Then send the request to Redlink using the following call:

curl -3 -X POST -H "Accept: application/json" 
-H "Content-Type: text/plain" 
-H "Authorization: Bearer <access-token>" 
-d @payload.txt 
"https://api.redlink.io/api/redlink/1.0.0/live?format=json"

By default the API returns the entities as RDF serialized using JSON-LD (or the serialization preferred). Because there are some people who could find RDF a find hard to manage (for instance in Javascript),  a SPARQL query could be optionally send to do the grounding directly in the API, getting so standard SPARQL Query Results format.  many situation where raw RDF could be a bit   Then the request would look like this:

curl -3 -X POST -H "Accept: application/json" 
-H "Content-Type: text/plain" 
-H "Authorization: Bearer <access-token>" 
-d @payload.txt 
"https://api.redlink.io/api/redlink/1.0.0/live?format=json&query=<SPARQL-query>"

You can use any SPARQL query, this is the one we use in our annotator tool:

PREFIX dct: <http://purl.org/dc/terms/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX fise: <http://fise.iks-project.eu/ontology/>
SELECT ?name ?start ?end ?uri ?confidence ?type ?description ?thumbnail ?lang ?desc1 ?desc2
WHERE {
  ?i a fise:EntityAnnotation ;
    fise:entity-label ?name ;
    fise:entity-reference ?uri ;
    fise:confidence ?confidence ;
    dct:relation ?r .
  ?r a fise:TextAnnotation ;
    fise:start ?start ;
    fise:end ?end .
  OPTIONAL { ?r dct:type ?type }
  OPTIONAL { ?uri skos:definition ?desc1 . FILTER (LANGMATCHES(LANG(?desc1),?lang )) }
  OPTIONAL { ?uri rdfs:comment ?desc2. FILTER (LANGMATCHES(LANG(?desc2),?lang )) }
  OPTIONAL { ?uri foaf:thumbnail ?thumbnail }
  {
    SELECT DISTINCT ?lang
    WHERE {
      ?l dct:type dct:LinguisticSystem ;
        dct:language> ?lang .
    }
  }
}
ORDER BY ?uri

To sum it up this would be the curl command line:

curl -3 -X POST -H "Accept: application/json" 
-H "Content-Type: text/plain" 
-H "Authorization: Bearer <access-code>" 
-d @payload.txt 
"https://api.redlink.io/api/redlink/1.0.0/live?format=json&query=SELECT%20%3Fname%20%3Fstart%20%3Fend%20%3Furi%20%3Fconfidence%20%3Ftype%20%3Fdescription%20%3Fthumbnail%20%3Flang%20%3Fdesc1%20%3Fdesc2%20WHERE%20%7B%20%20%20%20%20%20%20%20%3Fi%20a%20%3Chttp%3A%2F%2Ffise.iks-project.eu%2Fontology%2FEntityAnnotation%3E%3B%20%20%20%20%20%20%20%20%20%20%20%3Chttp%3A%2F%2Ffise.iks-project.eu%2Fontology%2Fentity-label%3E%20%3Fname%3B%20%20%20%20%20%20%20%20%20%20%20%3Chttp%3A%2F%2Ffise.iks-project.eu%2Fontology%2Fentity-reference%3E%20%3Furi%3B%20%20%20%20%20%20%20%20%20%20%20%3Chttp%3A%2F%2Ffise.iks-project.eu%2Fontology%2Fconfidence%3E%20%3Fconfidence%3B%20%20%20%20%20%20%20%20%20%20%20%3Chttp%3A%2F%2Fpurl.org%2Fdc%2Fterms%2Frelation%3E%20%3Fr.%20%20%20%20%20%20%20%3Fr%20a%20%3Chttp%3A%2F%2Ffise.iks-project.eu%2Fontology%2FTextAnnotation%3E%3B%20%20%20%20%20%20%20%20%20%20%20%3Chttp%3A%2F%2Ffise.iks-project.eu%2Fontology%2Fstart%3E%20%3Fstart%3B%20%20%20%20%20%20%20%20%20%20%20%3Chttp%3A%2F%2Ffise.iks-project.eu%2Fontology%2Fend%3E%20%3Fend.%20%20%20%20%20%20%20OPTIONAL%20%7B%3Fr%20%3Chttp%3A%2F%2Fpurl.org%2Fdc%2Fterms%2Ftype%3E%20%3Ftype.%7D%20%20%20%20%20%20%20OPTIONAL%20%7B%3Furi%20%3Chttp%3A%2F%2Fwww.w3.org%2F2004%2F02%2Fskos%2Fcore%23definition%3E%20%3Fdesc1.FILTER%20(LANGMATCHES(LANG(%3Fdesc1)%2C%3Flang%20))%7D%20%20%20%20%20%20%20OPTIONAL%20%7B%3Furi%20%3Chttp%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23comment%3E%20%3Fdesc2.FILTER%20(LANGMATCHES(LANG(%3Fdesc2)%2C%3Flang%20))%7D%20%20%20%20%20%20%20OPTIONAL%20%7B%3Furi%20%3Chttp%3A%2F%2Fxmlns.com%2Ffoaf%2F0.1%2Fthumbnail%3E%20%3Fthumbnail%7D%20%20%20%20%20%20%20%7B%20%20%20SELECT%20DISTINCT%20%3Flang%20%20%20%20%20%20%20%20%20%20%20WHERE%20%7B%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3Fl%20%3Chttp%3A%2F%2Fpurl.org%2Fdc%2Fterms%2Ftype%3E%3Chttp%3A%2F%2Fpurl.org%2Fdc%2Fterms%2FLinguisticSystem%3E.%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3Fl%20%3Chttp%3A%2F%2Fpurl.org%2Fdc%2Fterms%2Flanguage%3E%20%3Flang%20%20%20%20%20%20%20%7D%7D%7D%20ORDER%20BY%20%3Furi"

After the request is sent, you’ll receive a JSON response with the discovered entities. We’ll describe more in detail the response format in another post.