From IKS Project

Contents 1 FISE API review 1.1 RESTful API 1.2 Services API 1.3 Random ideas

FISE API review

Review of the FISE services and http APIs at the Furtwangen Hackathon, 2010/03/31.

See http://dl.dropbox.com/u/715349/iks/fise-apidocs-20100331-113.zip for the services API on which this review is based.

The HTTP API hasn't been formally specified yet, see "we got a launch" on this wiki for what we have now.

RESTful API

• Use FISE-specified Content-Types ("smart URIs") when PUTting or POSTing content, for example to include initial metadata with a document in a multipart PUT/POST body.
• POST to the FISE collection should generate an ID, PUT is for when the client knows where the data must be stored.
• IDs should be valid URL paths
• Use FISE-specified Content-Type for GET as well, to specify what you want (raw content? annotations? annotations from one engine only?). And if we want to be browser-friendly map selectors (additional extensions in the URL) and/or request parameters to those.

Stéfane is already doing some of this in the jersey module.

Services API

• ContentItem.id should be something more than a String, maybe an URI?
• The Store should receive binary content in an InputStream, and accept a Map of Hints for the incoming content (like the encoding of text/plain content for example, or size of a video stream, the incoming HTTP headers, etc.)
• We need an RDF schema for the enhancements that the engines produce. Keep it simple.
• Reto suggests using the term MediaType instead of MimeType as per RFC2616, and a dedicated type instead of string
• Use Enum for the EnhancementEngine's canEnhance return type (of course)
• We didn't discuss this suggestion, also by Reto: one solution would be to replace ID with UriRef that is a node in the graph, another would be to return a GraphNode (i.e. a graph with a designated center) with the latter approach the id could stay there if this is found useful.
• EnhancementEngine's computeEnhancements show throw an EngineException, so that the framework can log any problems.

Additional suggestion by Reto for the "UriRef that is a node in the graph" item above: the least invasive solution (not my preferred) would be to specify in the javadoc, that the graph contains a resource representing the content-node with the property fise:id (an ifp) pointing to an xsd:string with the id of the content-item.

Random ideas

• A standalone, no-storage, all synchronous version of FISE should be available, mainly for demos.