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:17] admin |
api4kb_persistent_storage [2013/03/17 16:12] (current) rmbell |
||
|---|---|---|---|
| Line 35: | Line 35: | ||
| CreateKB( | CreateKB( | ||
| - | in URI/URL knowledgeBase, | + | in URI/URL knowledgeBase, : the desired URI to associate to the (new) KB |
| - | out URL/URI effectiveKnowledgeBaseURI ); | + | out URL/URI effectiveKnowledgeBaseURI : the URI assigned to the (new) KB |
| - | + | ); | |
| - | Params : | + | |
| - | knowledgeBase (in) - the desired URI to associate 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 knowledge base already exists, its URI is returned. | 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 | TODO: discuss the use of URIs vs URLs | ||
| + | |||
| + | ---- | ||
| + | |||
| EnsureResourceIsInKB( | EnsureResourceIsInKB( | ||
| - | in URL knowledgeBase, | + | in URL knowledgeBase, : the target KB |
| - | in URI resourceId, | + | in URI resourceId, : the URI of the new resource |
| - | in URL resourceLocation, | + | in URL resourceLocation, : pointer to the actual resource |
| - | in Descr resourceDescriptor | + | in Descr resourceDescriptor : metadata describing the resource |
| out TODO ); | out TODO ); | ||
| - | Params : | ||
| - | knowledgeBase (in) : the target KB | ||
| - | 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 | Post-condition : Ensures that the target resource (at resourceLocation) is present in a KB and therein identified by resourceId | ||
| Line 67: | Line 64: | ||
| 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, | ||
| Line 75: | Line 76: | ||
| REST mapping : POST | 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)? | + | 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( | GetResourceFromKB( | ||
| - | in URL knowledgeBase, | + | in URL knowledgeBase, : the target KB |
| - | in URI resourceId, | + | 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 ) from a KB | Retrieves and returns the target resource ( identified by resourceId ) from a KB | ||
| + | |||
| + | |||
| + | |||
| + | ---- | ||
| ExportResourceFromKB( | ExportResourceFromKB( | ||
| - | in URL knowledgeBase, | + | in URL knowledgeBase, : the target KB |
| - | in URI resourceId, | + | in URI resourceId, : the URI of the resource to be accessed |
| - | in URL exportLocation, | + | in URL exportLocation, : the location where the resource should be exported |
| - | in Descr resourceDescriptor, | + | in Descr resourceDescriptor, : metadata to guide the export process |
| out TODO ); | out TODO ); | ||
| - | Params : | + | Pre-condition : the KB contains the resource mapped by resourceID. The client must have the appropriate rights to write at exportLocation. |
| - | knowledgeBase (in) : the target KB | + | |
| - | resourceID (in) : the URI of the resource to be accessed | + | |
| - | exportLocation (in) : the location where the resource should be exported | + | |
| - | 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 | 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. | 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 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. | 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( | DeleteResourceFromKB( | ||
| - | in URL knowledgeBase, | + | in URL knowledgeBase, : the target KB |
| - | in URI resourceId, | + | 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 149: | 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? | 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.1363547853.txt.gz · Last modified: 2013/03/17 15:17 by admin
Page Tools
