# Stanbol Enhancer services API

The Stanbol Enhancer services API defines the service interfaces for the components that collaborate to implement a Stanbol enhancement server.

See FISEcodeAndDocs on the IKS wiki for more information about Stanbol Enhancer (formally called IKS FISE).

The API has almost no external dependencies and is independent of OSGi or any other components model.

It currently has a dependency on the Clerezza MGraph interface, but we might want to replace that with a more generic "annotations" interface.

# Main design goals

The Stanbol enhancement server aims to:

- Make it very easy to use it as an external content enhancement/search engine, with a simple RESTful HTTP interface. Client PUTs or POSTs a piece of content to the Stanbol Enhancer, and can then retrieve the enhancements produced by the {@link org.apache.stanbol.enhancer.servicesapi.EnhancementEngine} that are active in the Stanbol Enhancement server, with a GET request.
- Make it simple for providers of enhancement engines (annotation, geolocation, etc...) to plug them into a Stanbol Enhancement server. With the current implementation, one just needs to implement a new {@link org.apache.stanbol.enhancer.servicesapi.EnhancementEngine} and supply it as an OSGi service in an OSGi bundle. See the Autotagging engine for an example that wraps a non-OSGi java content enhancement library.

TODO should we say "annotation" instead of "enhancement", and rename the interfaces accordingly?

# Main Stanbol Enhancer use-case

To help understand the API, here's an overview of the main Stanbol Enhancer use-case:

- Client PUTs or POSTs a piece of content to register it with Enhancer, supplied as a binary stream with a Content-Type (and optional initial metadata - not currently implemented).
- The {@link org.apache.stanbol.enhancer.servicesapi.EnhancementJobManager} goes through its list of {@link org.apache.stanbol.enhancer.servicesapi.EnhancementEngine} and finds out which ones can process the incoming {@link org.apache.stanbol.enhancer.servicesapi.ContentItem}. An engine can suggest enhancing the content synchronously or assynchronously, and the job manager can override those suggestions.
- The client GETs the {@link org.apache.stanbol.enhancer.servicesapi.ContentItem} using the same URL that it used in the previous PUT request, or the URL supplied by Enhancer (Location header) if a POST request was used to register the content.
- As some enhancement requests might be asynchronous, the returned data might include process information, for example "3 requests for enhancement still pending".

That's it. Not too hard.