[UI] Use case - Hypermedia APIs with input/output shapes description

[bergos]

Some Hypermedia APIs specifications, like TREE, Hydra, and others, may use SHACL shapes to describe the expected input and output data structures. The UI can use the shapes to generate forms for the expected input and validate the data provided by the user. The rendering of the output data can be improved by using the given SHACL shapes.

The backend logic can apply the request URL as the Named Graph or use a custom logic. The data exchange is constrained by the features of SHACL, and therefore, only triple serialization can be fully supported.

Some requests may transfer the input data as query parameters. SHACL shapes can be leveraged to translate to and from query parameters to RDF for uniform data processing.

The API description can be used by the frontend, but also for the backend logic. Additional information can be added for the backend to control the logic. Use cases where the client handles the data processing and persistence may require the same parameters, since the main difference is the location of the processing. Otherwise, both use cases are very similar.

Related:

• [UI] Use case - UI widgets and data updates with named graphs #672

Example:

@prefix api: <http://localhost:9000/api/>.
@prefix code: <https://code.schemas.link/>.
@prefix hyrang: <https://hyrang.org/>.
@prefix kg: <http://kg.internal.bergnet.org/schema/>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix schema: <http://schema.org/>.
@prefix sh: <http://www.w3.org/ns/shacl#>.

kg:Plants a rdfs:Class;
  hyrang:supportedOperation
    api:plantsGet,
    api:plantsPost.

api:pageShape a sh:NodeShape;
  sh:property [ a sh:PropertyShape;
      sh:maxCount 1;
      sh:minCount 1;
      sh:minInclusive 1;
      sh:path hyrang:limit;
      hyrang:variable "limit"
    ], [ a sh:PropertyShape;
      sh:maxCount 1;
      sh:minCount 1;
      sh:minInclusive 0;
      sh:path hyrang:offset;
      hyrang:variable "offset"
    ];
  hyrang:template "{?limit,offset}".

api:plantsGet a hyrang:SupportedOperation;
  code:arguments [
      code:name "global";
      code:value "true"
    ], [
      code:name "graph";
      code:value "*"
    ], [
      code:name "type";
      code:value kg:PlantSpecies
    ];
  code:implementedBy [ a code:EcmaScriptModule;
      code:link <file:../../node_modules/hyrang-toolbox/index.js#container>
    ];
  hyrang:expects api:pageShape;
  hyrang:method "GET";
  hyrang:returns api:plantsShape.

api:plantsPost a hyrang:SupportedOperation;
  code:implementedBy [ a code:EcmaScriptModule;
      code:link <file:./plants.js#post>
    ];
  hyrang:expects api:plantShape;
  hyrang:method "POST".

api:plantShape a sh:NodeShape;
  sh:property [ a sh:PropertyShape;
      sh:in (kg:Plants);
      sh:maxCount 1;
      sh:minCount 1;
      sh:path rdf:type
    ], [ a sh:PropertyShape;
      sh:maxCount 1;
      sh:minCount 1;
      sh:path schema:name
    ].

api:plantsShape a sh:NodeShape;
  sh:property [ a sh:PropertyShape;
      sh:path schema:hasPart;
      sh:node api:plantShape;
      sh:minCount 0;
    ].