Web Service API

This document explains the BigSemantics Web Service API.

Note: In practice, you should use BigSemantics provided client libraries to communicate with a BigSemantics web service instance if possible, to keep things simple and stupid.

Formats and common request parameters

For each API endpoint, we support 2 formats: json and jsonp:

• When json is used, the response will simply contains a serialized JSON object.

• When jsonp is used, you can include a query parameter callback in your request to specify the name of a callback function. When the request is correctly handled, the response will wrap the serialized JSON object as the first argument to the callback function. For example:

var serviceBase = 'http://myhost/BigSemanticsService/v3/';

function getMetadata(url, callbackName) {
  var encodedUrl = encodeURIComponent(url);
  var requestUrl = serviceBase + 'metadata.json?aid=' + appId
                   + '&appVer=' + appVer
                   + '&calback=' + callbackName
                   + '&url=' + encodeUrl;
  var requestElement = document.createElement('script');
  requestElement.setAttribute('src', requestUrl);
}

function log(result) {
  console.log("Result received: %O", result);
}

getMetadata('http://www.google.com', 'log');

Note: We recommend using the JSON API with XMLHttpRequest, rather than the JSONP API.

You can attach the following query parameters to your request:

• aid: Application ID, e.g. ideamache
• aver: Application version, e.g. 1.2.1
• uid: User ID, e.g. alice
• sid: Session ID, usually a hash string

These parameters generally will not change the behavior of the service, but will be reflected in the response, so that you can better decide what to do with the response.

Response data structure

For all request, response should contain a serialized JSON object, with the following fields:

• id: The task ID assigned by the service. Can be used e.g. to query task-specific logs
• request: Additional information if sent by the client and received along the request (as query parameters). This includes:
  • appId
  • appVer
  • userId
  • sessionId
• repository, wrapper, or metadata: The result. Different field names are for different types of result; see below. In most cases, you will need to use s.im.pl. to deserialize the result, to correctly handle cyclic references.

All API endpoints

♦ /BigSemanticsService/repository.{json|jsonp}, /BigSemanticsService/mmdrepository.{json|jsonp}

• Method: GET
• Result: the whole meta-metadata repository (repository of wrappers) as a serialized JSON object

♦ /BigSemanticsService/wrapper.{json|jsonp}, /BigSemanticsService/mmd.{json|jsonp}

• Method: GET
• Query parameters:
  • name: The name of the wrapper you want
  • url, uri: The URL of the web resource that you want a wrapper for
• Result: the target wrapper as a serialized JSON object

♦ /BigSemanticsService/metadata.{json|jsonp}

• Method: GET
• Query parameters:
  • url, uri: The URL of the web resource that you want metadata for
  • reload: If specified, the service will ignore cache, re-download the resource, and re-extract metadata from it
• Result: extracted semantics from the specified web resource, as a serialized JSON object

TBD