New Design of Client Library for Knora Resources

[tobiasschweizer]

This issue is related to dasch-swiss/dsp-api#1256. Details about how to generate the necessary client code could should be discussed there.

Read, Update, Add, Delete

Support of different operations (read, update, add, delete) on generic resources (incl. label) and values (incl. comment): handle conversions from and to JSON-LD and communicate with the Knora API.

I think we could use inheritance to model this. There could be a general resource and value skeleton that can be extended for specific operations (like in Knora).

So there could be a ReadResource when reading from Knora. Or the client would instantiate a CreateResource that would then have the method to serialise itself to JSON-LD. It think conceptually this is close to what we have in v2 in Knora.

The necessary code has to be generated in Knora so it keeps in sync (system properties).

Encapsulate Complex Queries

Support of knora-base concepts like compound resources that involve more than one API call (full resource request and Gravsearch queries): handle multiple async calls and update result when more data is available. This should simplify the use of compound resources like books that have pages. Same applies to images that have regions or videos with sequences.

Specific media types could be subclasses of ReadResource with additional information that is specific to the media type.

We have to make sure that this is in sync with knora-base.

Allow for User Provided Definitions

When the client submits a Gravsearch query, the type of the answer can be specified. The answer would be available directly as this type. In Gravsearch, not all properties of a resource have to be returned (see dasch-swiss/dsp-api#1256 (comment)) and the result could also contain nested resources or incoming properties.

I think in a first step, the conversion for the generic resource can be used. Then, there could be a check of all required properties (incl. those of nested resources).

[tobiasschweizer]

• AbstractResource
  • ReadResource: label, type, IRI, values
  • CreateResource: label, type, values
  • UpdateResource: label, type, IRI, values or value comments to be updated incl. current value IRIs or label to be updated, values and value comments to be created
  • DeleteResource: IRI

Depending on the operation, more or less information is required, see dasch-swiss/dsp-api#1256 (comment)

• AbstractResource
  • AbstractComplexResource
    • StillImageRepresentationResource (may contain regions)
    • MovingImageRepresentation (may have sequences)
    • AudioRepresentationResource (may have sequences)
    • CompoundResource (has parts pointing to it)
    • IncomingLinksResource (pointed to by other resources)

The client library should offer convenience methods to handle the subclasses of AbstractComplexResource: there should be a method like getCompoundResource that gets both the compound resource and its parts, performing several queries. A prototypical implementation (only for StillImageRepresentations) of this functionality is available here:

https://github.com/dhlab-basel/beol/blob/fef23318a58fb502cab4677161431df95f4dfff0/src/app/resource/beol-resource.ts#L58-L125

[tobiasschweizer]

note to myself: when making a get request for a resource, the timestamp should be an optional parameter.

[kilchenmann]

Where will I find the gui-order of properties? In @knora/core we added an array of type GuiOrder {position: number, propertyIri: string} to resource's ontology information. We need somewhere an array of properties to iterate through in the html template. Please have a look at the properties-view.component.html in @knora/viewer module which is used by resource-view.component.

[tobiasschweizer]

On a ReadResource you can find the property entityInfo which contains a IResourceClassAndPropertyDefinitions. There you will find the ClassDefinition for the resource you are looking at. The ClassDefinition contains propertiesList that lists all the properties defined for the resource class, including cardinality and gui order :

https://github.com/dasch-swiss/knora-api-js-lib/blob/c2a91a679b050c505923f1dce1fc9da742ad96d4/src/models/v2/ontologies/class-definition.ts#L3-L48