APIs for persistent storage Link to API4KB Main Page
Clarification Administration APIs. Even if (also) exposed as services, the knowledge base administration APIs are not “services” in the sense that they provide (computational) capabilities to the client, but rather FOR the client. Moreover, as soon as we expose the APIs as services, there could be more than one client active at the same time. So, the APIs should be:
1) idempotent from the client's perspective
2) stateless from the execution server's perspective
3) stateful from the knowledge-base perspective!
I.e. there is a “state”, but that is maintained at the KB level only.
in URI/URL knowledgeBase, : the desired URI to associate to the (new) KB out URL/URI effectiveKnowledgeBaseURI : the URI assigned to the (new) KB );
Post-condition : Ensures that a knowledgeBase exists for the given URI (at the given URL??)
REST mapping : POST
Creates a new knowledge base and associates it to the given URI. If the knowledge base already exists, its URI is returned.
TODO: discuss the use of URIs vs URLs
in URL knowledgeBase, : the target KB in URI resourceId, : the URI of the new resource in URL resourceLocation, : pointer to the actual resource in Descr resourceDescriptor : metadata describing the resource out TODO );
Post-condition : Ensures that the target resource (at resourceLocation) is present in a KB and therein identified by resourceId REST mapping : PUT
Creates the resource if not present. Otherwise, it replaces the existing resource with the one passed as argument. If the resource at resourceLocation is already mapped to resourceID, nothing will happen.
in URL knowledgeBase, in URI resourceId, in URL resourceLocation, in Descr resourceDescriptor, out TODO );
REST mapping : POST
TODO: This method should be defined. What is the exact semantics of updating a resource in a KB, as opposed to setting it? It could be interpreted in terms of versioning? Or the “old” and “new” resources should be “merged” (whatever that means)?
in URL knowledgeBase, : the target KB in URI resourceId, : the URI of the resource to be accessed out TODO );
Post-condition : The KB is not altered
REST mapping : GET
Retrieves and returns the target resource ( identified by resourceId ) from a KB
in URL knowledgeBase, : the target KB in URI resourceId, : the URI of the resource to be accessed in URL exportLocation, : the location where the resource should be exported in Descr resourceDescriptor, : metadata to guide the export process out TODO );
Pre-condition : the KB contains the resource mapped by resourceID. The client must have the appropriate rights to write at exportLocation.
Integrity : the format specified by resourceDescriptor is compatible with the nature of the resource
Post-condition : the exportLocation will contain a serialized copy of the resource mapped by resourceId, as defined by resourceDescriptor. The KB is not altered.
REST mapping : POST
Exports a resource from a target KB to exportLocation, in the format specified in resourceDescriptor. Any previous content at exportLocation will be overridden. The operation is read-only from the KB's perspective, so the exportLocation can't be part of the KB itself.
in URL knowledgeBase, : the target KB in URI resourceId, : the URI of the resource to be deleted out TODO );
Pre-condition : the KB contains a resource mapping for resourceID ???
Post-condition : the KB no longer contains a resource mapping for resourceID
REST mapping : DELETE
Removes a resource from a KB, if present. No effect otherwise ?
The 3 desiderata above, instead, make the Connect / Start Tx / Commit Tx APIs much more questionable. Both from a design - they are too “low-level” to be exposed as services - and architecture perspective - they fail to support multiple clients.
Additional questions - URLs (resource locations) vs. URIs (identifiers), or both, and how are we referring to what
But the transactionality is a different matter.. I don't think we should drop it altogether. Instead, I would investigate the concurrent versioning systems (such as Git) or, possibly better, the area of optimistic concurrent editing . Does anyone already have some familiarity with these fields - or can anyone suggest other (better) alternatives?
Additional capability to have some means to know when an external resource that has some relationship to the knowledge base (as in a subset is loaded in the KB) has changed may be useful (could be UUID driven, talk with MIWIG for strategies).