User Tools

Site Tools


api4kb_persistent_storage

====== Differences ====== This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
api4kb_persistent_storage [2013/03/17 10:50]
admin [Questions]
api4kb_persistent_storage [2013/03/17 16:12] (current)
rmbell
Line 13: Line 13:
       * Truth maintenance (may depend on the reasoner)       * Truth maintenance (may depend on the reasoner)
       * Explanation support, at least through the interface mechanism       * Explanation support, at least through the interface mechanism
 +
 +
 +
 +----
 +
 +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.
 +
 +
 +
 +----
 +
 +
 +CreateKB(
 +    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
 +
 +----
 +
 +
 +
 +EnsureResourceIsInKB(
 +    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.
 +
 +
 +----
 +
 +UpdateResourceInKB(
 +    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)?
 +
 +
 +
 +----
 +
 +
 +GetResourceFromKB(
 +    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
 +
 +
 +
 +----
 +
 +
 +ExportResourceFromKB(
 +    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.
 +
 +
 +----
 +
 +
 +DeleteResourceFromKB(
 +    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.
 +
 +
 +
  
  
Line 22: Line 150:
    * At a minimum, we would have to be able to expose whatever capability a given back-end has for supporting change management    * At a minimum, we would have to be able to expose whatever capability a given back-end has for supporting change management
    * So -- we should know what capabilities a particular KB / reasoner has, which might mean that we should be able to ask whether or not the KB has certain change management capabilities,​ and then ask it to turn such capabilities on if available    * So -- we should know what capabilities a particular KB / reasoner has, which might mean that we should be able to ask whether or not the KB has certain change management capabilities,​ and then ask it to turn such capabilities on if available
 +   * If the KB/reasoner only has partial support for such capabilities,​ it should "do what it can"
 +   * Use case might be cloud-based,​ where one is selling services including reasoning services, and you may not know whether or not the reasoner can support incremental update ...
 +   * This is primarily an issue where there are brokered services, and you are negotiating which service to use based on whether or not that service can provide fully documented change management capabilities
 +   * The main issue on the table is whether or not we should be able to query a KB/service to understand what it's capability is -- a meta capability query
 +
 +
 +Additional questions - URLs (resource locations) vs. URIs (identifiers),​ or both, and how are we referring to what
 +  - Deep vs. shallow, or cascading operations with respect to deletion
 +  - incremental update (as opposed to delete/​re-add style update, which would result in a new identifier)
 +  - differential,​ incremental,​ in-place update, as opposed to some sort of ugly replace operation
 +
 +
 +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 [4]. 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).
api4kb_persistent_storage.1363531816.txt.gz ยท Last modified: 2013/03/17 10:50 by admin