====== Differences ====== This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Last revision Both sides next revision | ||
api4kb_persistent_storage [2013/03/17 15:25] admin |
api4kb_persistent_storage [2013/03/17 16:05] 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 66: | Line 63: | ||
Creates the resource if not present. Otherwise, it replaces the existing resource with the one passed as argument. | 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. | If the resource at resourceLocation is already mapped to resourceID, nothing will happen. | ||
+ | |||
+ | |||
+ | ---- | ||
UpdateResourceInKB( in URL knowledgeBase, | UpdateResourceInKB( in URL knowledgeBase, | ||
Line 75: | Line 75: | ||
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 158: | Line 162: | ||
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). |