Keyword Aggregator Web Service Documentation

Last modified by Benn, David (IM&T, Waite Campus) on Jul 07, 2017

Overview

The Keyword Aggregator Web Service provides the following functions:

  • Search for keyword across aggregated vocabularies
  • Storage of keyword usage information
  • Addition of a new keyword
  • Vocabulary namespace listing

The base URL is determined by application settings, e.g. http://scikey.org, and is represented as "base-URL" below. 

Web service responses and payloads use JSON.

Functions

Keyword Search

Method: GET

The service end-point for search is base-URL/api/search

Parameter Value Valid Response Error Response Example
None None None

Status: 400

Text: No search term specified as a Query String Argument

http://scikey.org/api/search
keyword

search string, e.g.

  • keyword=bio
  • keyword=astronomy

Status: 200

JSON result containing term, sum (of weights), text_value, prefLabel

Status: 400

Text: Query String Argument search terms must be at least 3 characters long

http://scikey.org/api/search?keyword=bi
_format

requested format:

  • _format=application/json
  • _format=application/json-p

optional

Status: 200

application/json: JSON result containing term, sum (of weights), text_value, prefLabel

application/json-p: JSON result containing term, sum (of weights), text_value, prefLabel wrapped by "jQueryN_M();"


None


Text: Requests for other formats (e.g. XML) will default to JSON.

http://scikey.org/api/search?keyword=bio&_format=application/json
limit

positive integer value specifying the maximum number of results to be returned, e.g.

  • limit=5

optional (default: 10)

Status: 200

JSON result containing term, sum (of weights), text_value, prefLabel, limited to the maximum number of results requested.

Status: 400

Text: Limit must be a positive integer value

http://scikey.org/api/search?keyword=bio&limit=5

Sample JSON Response for http://scikey.org/api/search?keyword=bio&limit=1
{
    "head": {
        "vars": [
            "graph_name",
            "term",
            "sum",
            "text_value",
            "prefLabel"
        ]
    },
    "results": {
        "bindings": [
            {
                "vocab_subject": {
                    "value": "computer science",
                    "type": "literal",
                    "xml:lang": "en"
                },
                "sum": {
                    "value": "40",
                    "type": "typed-literal",
                    "datatype": "http://www.w3.org/2001/XMLSchema#integer"
                },
                "vocab_title": {
                    "value": "Wikipedia Computer Science Terms",
                    "type": "literal",
                    "xml:lang": "en"
                },
                "prefLabel": {
                    "value": "Computational Biology",
                    "type": "literal"
                },
                "term": {
                    "value": "http://scikey.org/id/vocab/wikipediacompsci/def/ComputationalBiology",
                    "type": "uri"
                },
                "text_value": {
                    "value": "Computational Biology",
                    "type": "literal"
                },
                "vocab_status": {
                    "value": "http://purl.org/linked-data/registry#statusSubmitted",
                    "type": "uri"
                }
            }
        ]
    }
}

Note that this is a standard, SPARQL response encoded in JSON.

Keyword Usage Storage

Method: POST

The service end-point for the usage reporting is base-URL/api/store

Parameter Value Valid Response Error Response Example
None

JSON value for POST with:

  • ownerId: integer or string
  • instanceId: integer or string
  • terms: array of term URIs

Status: 201

Message: inserted

Status: 500

Error message

http://scikey.org/api/store
with POST data:
{
 instanceId: "MODSIM_OWS",

ownerId: 86,

arrivalTime: 1450326342,

clientId: "fred",

 terms: [http://mssanz.org.au/modsim/def/root_biomass,
         http://mssanz.org.au/modsim/def/biological_invasion,
         http://mssanz.org.au/modsim/def/biofuels]
}

Keyword Addition

Method: POST

The service end-point for search is base-URL/api/widget_add_keyword

Parameter Value Valid Response Error Response Example
None

JSON value for POST with:

  • keyword: string
  • keyword_desc: string (optional)

keyword_desc is an optional description for the keyword.

It may be the empty string.

Status: 201

Message: added

Status: 500

Error message

http://scikey.org/api/widget_add_keyword
with POST data:
{

keyword: foobar,

keyword_desc: A bar owned by a foo

}

Vocabulary Namespaces

Method: GET

The service end-point for search is base-URL/api/vocab_namespaces

Parameter Value Valid Response Error Response Example
None None

Status: 200

JSON result term, sum (of weights), text_value, prefLabel

JSON response containing vocabulary namespaces. For example,

the following shows two vocabulary namespaces: default and

user-defined:

{"head": {"vars": ["graph"]}, 
 "results": 
 {
  "bindings": 
  [{"graph": {"type": "uri", "value": "default"}}, 
   {"graph": {"type": "uri", "value": "user-defined"}}]
 }
}
None

http://scikey.org/api/vocab_namespaces

Comments

    Add new comment