api4kb_persistent_storage
====== Differences ====== This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
api4kb_persistent_storage [2013/03/17 15:02] admin |
api4kb_persistent_storage [2013/03/17 16:12] (current) rmbell |
||
|---|---|---|---|
| Line 14: | Line 14: | ||
| * Explanation support, at least through the interface mechanism | * Explanation support, at least through the interface mechanism | ||
| + | |||
| + | |||
| + | ---- | ||
| Clarification | Clarification | ||
| Line 27: | Line 30: | ||
| - | -------------------------------- | ||
| - | ***** CreateKB( | + | ---- |
| - | in URI/URL knowledgeBase, | + | |
| - | out URL/URI effectiveKnowledgeBaseURI ); | + | |
| - | Params : | + | CreateKB( |
| - | knowledgeBase (in) : the desired URI to | + | in URI/URL knowledgeBase, : the desired URI to associate to the (new) KB |
| - | associate to the (new) KB | + | out URL/URI effectiveKnowledgeBaseURI : the URI assigned to the (new) KB |
| - | effectiveKnowledgeBaseURI (out) : the URI assigned to the (new) KB | + | ); |
| - | Post-condition : Ensures that a knowledgeBase exists for the given URI | + | |
| - | (at the given URL??) | + | Post-condition : Ensures that a knowledgeBase exists for the given URI (at the given URL??) |
| REST mapping : POST | REST mapping : POST | ||
| - | Creates a new knowledge base and associates it to the given URI. If the | + | Creates a new knowledge base and associates it to the given URI. If the knowledge base already exists, its URI is returned. |
| - | knowledge base already exists, its URI is returned. | + | |
| TODO: discuss the use of URIs vs URLs | TODO: discuss the use of URIs vs URLs | ||
| + | ---- | ||
| - | ***** SetResourceToKB( | + | |
| - | in URL knowledgeBase, | + | |
| - | in URI resourceId, | + | EnsureResourceIsInKB( |
| - | in URL resourceLocation, | + | in URL knowledgeBase, : the target KB |
| - | in Descr resourceDescriptor | + | 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 ); | out TODO ); | ||
| - | Params : | + | |
| - | knowledgeBase (in) : the target KB | + | Post-condition : Ensures that the target resource (at resourceLocation) is present in a KB and therein identified by resourceId |
| - | resourceID (in) : the URI of the new | + | |
| - | resource | + | |
| - | resourceLocation (in) : pointer to the actual | + | |
| - | resource | + | |
| - | resourceDescriptor (in) : metadata describing the | + | |
| - | resource | + | |
| - | Post-condition : Ensures that the target resource (at resourceLocation) | + | |
| - | is present in a KB and therein identified by resourceId | + | |
| REST mapping : PUT | REST mapping : PUT | ||
| - | Creates the resource if not present. Otherwise, it replaces the existing | + | Creates the resource if not present. Otherwise, it replaces the existing resource with the one passed as argument. |
| - | resource with the one passed as argument. | + | If the resource at resourceLocation is already mapped to resourceID, nothing will happen. |
| - | If the resource at resourceLocation is already mapped to resourceID, | + | |
| - | nothing will happen. | + | |
| - | ????? UpdateResourceInKB( in URL knowledgeBase, | + | |
| + | ---- | ||
| + | |||
| + | UpdateResourceInKB( | ||
| + | in URL knowledgeBase, | ||
| in URI resourceId, | in URI resourceId, | ||
| in URL resourceLocation, | in URL resourceLocation, | ||
| in Descr resourceDescriptor, | in Descr resourceDescriptor, | ||
| out TODO ); | out TODO ); | ||
| + | |||
| REST mapping : POST | REST mapping : POST | ||
| - | TODO. This method should be defined. What is the exact semantics of | + | 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)? |
| - | 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, | + | ---- |
| - | in URI resourceId, | + | |
| + | |||
| + | GetResourceFromKB( | ||
| + | in URL knowledgeBase, : the target KB | ||
| + | in URI resourceId, : the URI of the resource to be accessed | ||
| out TODO ); | out TODO ); | ||
| - | Params : | + | |
| - | knowledgeBase (in) : the target KB | + | |
| - | resourceID (in) : the URI of the | + | |
| - | resource to be accessed | + | |
| Post-condition : The KB is not altered | Post-condition : The KB is not altered | ||
| + | |||
| REST mapping : GET | REST mapping : GET | ||
| - | Retrieves and returns the target resource ( identified by resourceId ) | + | Retrieves and returns the target resource ( identified by resourceId ) from a KB |
| - | from a KB | + | |
| - | ***** ExportResourceFromKB( | + | |
| - | in URL knowledgeBase, | + | ---- |
| - | in URI resourceId, | + | |
| - | in URL exportLocation, | + | |
| - | in Descr resourceDescriptor, | + | 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 ); | out TODO ); | ||
| - | Params : | + | |
| - | knowledgeBase (in) : the target KB | + | Pre-condition : the KB contains the resource mapped by resourceID. The client must have the appropriate rights to write at exportLocation. |
| - | resourceID (in) : the URI of the | + | |
| - | resource to be accessed | + | Integrity : the format specified by resourceDescriptor is compatible with the nature of the resource |
| - | exportLocation (in) : the location where | + | |
| - | the resource should be exported | + | Post-condition : the exportLocation will contain a serialized copy of the resource mapped by resourceId, as defined by resourceDescriptor. The KB is not altered. |
| - | resourceDescriptor (in) : metadata to guide the | + | |
| - | export process | + | |
| - | 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 | REST mapping : POST | ||
| - | Exports a resource from a target KB to exportLocation, in the format | + | 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. |
| - | 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, | + | ---- |
| - | in URI resourceId, | + | |
| + | |||
| + | DeleteResourceFromKB( | ||
| + | in URL knowledgeBase, : the target KB | ||
| + | in URI resourceId, : the URI of the resource to be deleted | ||
| out TODO ); | out TODO ); | ||
| - | Params : | + | |
| - | knowledgeBase (in) : the target KB | + | |
| - | resourceID (in) : the URI of the | + | |
| - | resource to be deleted | + | |
| Pre-condition : the KB contains a resource mapping for resourceID ??? | Pre-condition : the KB contains a resource mapping for resourceID ??? | ||
| + | |||
| Post-condition : the KB no longer contains a resource mapping for resourceID | Post-condition : the KB no longer contains a resource mapping for resourceID | ||
| + | |||
| REST mapping : DELETE | REST mapping : DELETE | ||
| Line 143: | Line 137: | ||
| -------------------------------- | -------------------------------- | ||
| - | The 3 desiderata above, instead, make the Connect / Start Tx / Commit Tx | + | 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. |
| - | 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 164: | Line 154: | ||
| * 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 | * 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 | * 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.1363546945.txt.gz · Last modified: 2013/03/17 15:02 by admin
Page Tools
