Augmentation API

The Augmentation API provides a means for enriching existing structured data against a dataset in Kasabi, without the need to write specific queries or search patterns.

Overview

The basic processing steps in the API are as follows:

• The input document, e.g. an RSS 1.0 feed, is examined and all identifiers (URIs) from the feed are extracted.
• For each of the identifiers, a query is done against the underlying dataset, to extract any available data. The query used to extract data is consistent with that used by the Lookup API.
• The input document is then reconstructed, with any additional data added as annotations.

The end result is that the original document is returned, optionally enhanced with data from the underlying dataset.

The Augmentation API does not apply any entity extraction rules on text contained in input documents, so it is not intended to help annotate arbitrary text sources. Instead it supports improving the level of detail available about entities that are already identified in the input document. Also note that links embedded in, e.g. HTML fragments in full-content RSS feeds, are ignored.

Currently the service is limited to supporting the enrichment of RSS 1.0 feeds, making it compatible with the output from the Search API. This is because RSS 1.0, is a cleanly extensible document format, making it easy for annotations to be added to the document without impacting its meaning. In future the API will be expanded to support more input formats, e.g. arbitrary RDF or Atom feeds.

Basic API Reference

Endpoint URL

The base URI of an Augmentation API will be displayed on the homepage for the API

Authentication

To access the API will require use of your API key. For more information on Kasabi authentication options read the authentication documentation.

Parameters

All instances of the Augmentation API accept a data-uri parameter which is used to identity the input document. E.g:

http://api.kasabi.com/dataset/nasa/apis/augmentation?apikey=...&data-uri=http://www.example.org/feed.rss

The value of the data-uri parameter should be the URL encoded address of feed to be annotated.

The augmentation service will fetch the results at this URI, automatically following up to three redirects. The fetch request will include an Accept header of application/rss+xml only. Alternatively, data can be submitted to the service using an HTTP POST. In this case the body of the POST request should contain the full RSS feed to be annotated.

HTTP Response Codes

Clients should be prepared to receive any valid HTTP response code. The following table lists the most frequently used codes

Please also review our additional notes on response codes and error reporting.

Response Formats

Currently only RSS 1.0 and RDF/JSON are supported.

These formats can be requested using the usual content negotiation options.