From 0f611c3848dd4927b6f65c7635257c5f2e2ea0e1 Mon Sep 17 00:00:00 2001 From: kburger <6997485+kburger@users.noreply.github.com> Date: Wed, 10 Mar 2021 15:53:58 +0100 Subject: [PATCH 1/2] Introduce Usage docs (#18) --- docs/index.rst | 9 ++- docs/usage/api-usage.rst | 115 ++++++++++++++++++++++++++++++++ docs/usage/usage.rst | 140 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 263 insertions(+), 1 deletion(-) create mode 100644 docs/usage/api-usage.rst create mode 100644 docs/usage/usage.rst diff --git a/docs/index.rst b/docs/index.rst index f6c61b5..0cb2499 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,5 @@ FAIR Data Point Reference Implementation Documentation -============================= +====================================================== .. toctree:: :caption: About @@ -17,6 +17,13 @@ FAIR Data Point Reference Implementation Documentation deployment/production-deployment deployment/advanced-configuration +.. toctree:: + :caption: Usage + :maxdepth: 2 + + usage/usage + usage/api-usage + .. toctree:: :caption: OpenRefine Extension :maxdepth: 2 diff --git a/docs/usage/api-usage.rst b/docs/usage/api-usage.rst new file mode 100644 index 0000000..f38dcd3 --- /dev/null +++ b/docs/usage/api-usage.rst @@ -0,0 +1,115 @@ +.. _api-usage: + +********* +API Usage +********* + +The **FAIR Data Point** exposes API endpoints that allow consumers to interact with the metadata. Some of the endpoints are available for all users, while others require an API token for authorization. + +Obtaining an API token +====================== + +In order to obtain an API token, you invoke the ``/tokens`` endpoint with your user credentials. + +.. code :: bash + + curl -X POST -H "Accept: application/json" \ + -H "Content-Type: application/json" \ + -d '{ "email": "user@example.com", "password": "secret" }' \ + https://fdp.example.com/tokens + +A successful call will return a ``JSON`` object with a token. + +.. code :: + + { "token": "efIobn394nvJJFJ30..." } + +Issueing a request with the authorization token +------------------------------------------------ + +Subsequent requests should use this token in the `Authorization` header. The authorization type is a `Bearer `_ token. + +.. code :: bash + + curl -H "Authorization: Bearer efIobn394nvJJFJ30..." \ + -H "Accept: application/json" https://fdp.example.com/users + +Interacting with metadata +========================= + +The metadata layers as defined by the :ref:`resource-definitions` are exposed through their respective endpoints. The general approach is that each layer, defined by its ``prefix``, supports a number of read and write HTTP methods. + +======== ====================== ======================== +Method URL pattern Functionality +======== ====================== ======================== +``GET`` ``/${prefix}/${uuid}`` :ref:`retrieve-metadata` +``POST`` ``/${prefix}`` :ref:`create-metadata` +``PUT`` ``/${prefix}/${uuid}`` :ref:`update-metadata` +======== ====================== ======================== + +.. _retrieve-metadata: + +Retrieving metadata +------------------- + +Retrieving metadata is open for GET requests without authorization. In the following example, we retrieve a ``Dataset`` resource by issuing a ``GET`` request to the ``/dataset`` prefix followed by its identifier (a UUID). + +.. code :: bash + + curl -H "Accept: text/turtle" https://fdp.example.com/dataset/58d7fbde-6c16-483e-b152-0f3ced131ca9 + +.. _create-metadata: + +Creating metadata +----------------- + +New metadata can be created by ``POST``-ing the content to the appropriate endpoint. First we will create a file called ``metadata.ttl`` to store our new metadata. + +.. code :: turtle + + @prefix dcat: . + @prefix dct: . + @prefix foaf: . + + <> a dcat:Dataset ; + dct:title "test" ; + dct:hasVersion "1.0" ; + dct:publisher [ a foaf:Agent ; foaf:name "Example User" ] ; + dcat:theme ; + dct:isPartOf . + +This metadata can be created by the following ``POST`` request. + +.. code :: bash + + curl -H "Authorization: Bearer efIobn394nvJJFJ30..." \ + -H "Content-Type: text/turtle" \ + -d @metadata.ttl https://fdp.example.com/dataset + +When created, the metadata is initially in a ``DRAFT`` state. To publish the metadata using the API you can issue the following ``PUT`` request to transistion the metadata from the ``DRAFT`` state to the ``PUBLISHED`` state. + +.. code :: bash + + curl -X PUT -H "Authorization: Bearer efIobn394nvJJFJ30..." \ + -H "Accept: application/json" \ + -H "Content-Type: application/json" \ + -d '{ "current": "PUBLISHED" }' \ + https://fdp.example.com/dataset/79508287-a2a7-4ae2-95b3-3f595e3088cc/meta/state + +.. _update-metadata: + +Update metadata +--------------- + +Existing metadata can be updated by issuing a ``PUT`` request with the request body being the updated metadata. + +.. code :: bash + + curl -X PUT -H "Authorization: Bearer efIobn394nvJJFJ30..." \ + -H "Content-Type: text/turtle" \ + -d @metadata.ttl https://fdp.example.com/dataset/79508287-a2a7-4ae2-95b3-3f595e3088cc + +API endpoint listing +==================== + +The available APIs are documented using `OpenAPI `_. In the ``/swagger-ui.html`` endpoint the APIs are visualized through `Swagger UI `_. diff --git a/docs/usage/usage.rst b/docs/usage/usage.rst new file mode 100644 index 0000000..c70e12b --- /dev/null +++ b/docs/usage/usage.rst @@ -0,0 +1,140 @@ +***** +Usage +***** + +.. _resource-definitions: + +Resource definitions +==================== + +The **FAIR Data Point** reference implementations introduces the concept of **Resource Definitions**. A resource definition captures housekeeping data about a metadata resource. + +Resource definitions can be accessed from the reference implementation user interface, in the dashboard of an admin user. Here the resource definitions can be managed. + +Managing resource definitions +----------------------------- + +Resource definitions can be :ref:`created `, :ref:`modified `, or :ref:`deleted `. + +.. _create-resource-definition: + +Creating resource definitions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When creating a new resource definition, the user interface presents you a form where a resource can be defined through a number of properties. + +**Name** defines the human readable name for a resource definition. This name is used in the admin dashboard to identify the definitions, and does not affect a definition on the functional level. For example, for the default ``dcat:Dataset`` resource, the human readable name would be ``"Dataset"``. + +**URL Prefix** defines the URL path for a resource. This context path should be a unique identifier, unique in the scope of the other resource defined within the FAIR Data Point instance. For example, for the ``dcat:Dataset`` resource the prefix is ``dataset``. + +**Target Class URIs** links the :ref:`shape definitions ` to a resource definition. In the current implementation, each shape that should be applied to the resource must be listed here. The expected URI value must match the ``sh:targetClass`` value of the shape definition. A common example is to list the ``dcat:Resource`` shape target class along with the specific subclass for the resource, like ``dcat:Dataset``. + +**Children** defines child resources, if any. This applies when the resource acts as a parent resource for other types of resources. Children are defined by the following properties to provide directives for both the server and the client side. + +* *Child Resource* links to the child's *resource definition*. The child resource must be defined beforehand. +* *Child Relation URI* defines the predicate IRI that links the parent to the child on the metadata instance level. A common example is the link from a ``dcat:Dataset`` to a ``dcat:Distribution``; these resources are linked by the ``dcat:distribution`` predicate. +* *Child List View Title* defines a literal value to be displayed as a section header for the child resources in the user interface. +* *Child List View Tags URI* defines the predicate IRI for values that are displayed in the user interface whenever the child resources are listed. A common example is ``dcat:theme`` for ``dcat:Dataset`` resources. +* *Child List View Metadata* defines predicate IRIs for values that are listed in the child resource summary. + +**External links** defines predicate IRIs and literal values to be displayed in the user interface for primary interaction with a resource. A common example is for the ``dcat:Distribution`` resource, ``dcat:accessURL`` is mapped to an ``Access URL`` literal, and displayed prominently in the user interface. + +.. _modify-resource-definition: + +Modifying resource definitions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When modifying a resource definition, not all properties are writable. Some properties are write-protected to ensure the internal consistency of the system. + +The **URL Prefix** and the **Target Class URIs** are not writable. + +The other properties, like child resources and external links are writable, and can be expanded or modified after the initial creation of the resource definition. + +.. _delete-resource-definition: + +Deleting resource definitions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Deleting a resource definition should be used with caution. Existing metadata instances are no longer accessible after the resource definition is deleted. This includes child resources, if those are not linked to other resources. + +.. _shapes: + +Shapes +====== + +The **FAIR Data Point** reference implementation uses `SHACL `_ to add validation constraints to the metadata model. + +Creating a new shape +-------------------- + +A typical resource shape contains the following key elements: + +* ``sh:targetClass`` to indicate the type of resource the shape applies to +* ``sh:property`` for each resource property + + * ``sh:path`` defines the predicate IRI + * ``sh:nodeKind``/``sh:datatype`` defines the object type + * ``sh:minCount``/``sh:maxCount`` defines the property cardinality + +.. code :: turtle + + @prefix sh: . + @prefix dash: . + @prefix dct: . + @prefix dcat: . + @prefix ex: . + + :MyResourceShape a sh:NodeShape ; + sh:targetClass ex:MyResourceType ; + sh:property [ + sh:path ex:value ; + sh:nodeKind sh:Literal ; + sh:minCount 1 ; + sh:maxCount 2 ; + ] . + +User interface directives +------------------------- + +The `DASH `_ vocabulary introduces extensions to the core SHACL model. One of the extensions is focused on providing user interface hints for shape properties. Introducing or removing a ``dash:viewer`` or ``dash:editor`` property to a ``sh:PropertyShape`` instance influences how the user interface displays the property value. + +.. code :: turtle + + sh:property [ + sh:path ex:value ; + sh:nodeKind sh:Literal ; + dash:viewer dash:LiteralViewer ; + dash:editor dash:TextFieldEditor ; + ] + +By adding a ``dash:viewer`` statement, the user interface is instructed to show the property value when the resource metadata is displayed. Removing a ``dash:viewer`` statement will instruct the user interface will not render the property value at all. The value will still be present in the metadata model. The supported set of viewers (version 1.6.0): + +* ``sh:LabelViewer`` +* ``sh:URIViewer`` + +By adding a ``dash:editor`` statement, the editor form in the user interface will show an edit field for the property. Removing a ``dash:editor`` statement will prevent the property from being edited. This could be intended behaviour for properties that are generated server side. The supported set of editors (version 1.6.0): + +* ``sh:TextFieldEditor`` +* ``sh:TextAreaEditor`` +* ``sh:URIEditor`` +* ``sh:DatePickerEditor`` + +Extending an existing shape +--------------------------- + +Extending an existing shape can be achieved by targeting the same ``sh:targetClass``. For example, to extend the existing ``dcat:Dataset`` shape, an extension shape could look like the following: + +.. code :: turtle + + :MyExtension a sh:NodeShape ; + sh:targetClass dcat:Dataset ; + sh:property [ + sh:path ; + sh:nodeKind sh:Literal ; + sh:minCount 1 ; + ] . + +Limitations +----------- +* The current implementation does not provide proper support for overriding properties when an existing resource is extended +* The set of supported ``dash:viewer`` and ``dash:editor`` types does not cover the full range as specified in the DASH specs. From 141e03fb7e2a4fb92a9719245306f9e88dc0ce3d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Wed, 10 Mar 2021 16:05:56 +0100 Subject: [PATCH 2/2] Release 1.8.0 --- docs/conf.py | 2 +- docs/deployment/advanced-configuration.rst | 4 ++-- docs/deployment/local-deployment.rst | 16 ++++++++-------- docs/deployment/production-deployment.rst | 4 ++-- docs/development/changelog.rst | 6 ++++++ docs/usage/usage.rst | 4 ++-- 6 files changed, 21 insertions(+), 15 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index e18266e..b65e597 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,7 +22,7 @@ author = 'Dutch Techcentre for Life Sciences' # The full version, including alpha/beta/rc tags -release = '1.7.0' +release = '1.8.0' # -- General configuration --------------------------------------------------- diff --git a/docs/deployment/advanced-configuration.rst b/docs/deployment/advanced-configuration.rst index 19e7b0b..bd53368 100644 --- a/docs/deployment/advanced-configuration.rst +++ b/docs/deployment/advanced-configuration.rst @@ -230,13 +230,13 @@ have to set ``PUBLIC\_PATH`` ENV variable, in this example to version: '3' services: fdp: - image: fairdata/fairdatapoint:1.7.0 + image: fairdata/fairdatapoint:1.8.0 volumes: - ./application.yml:/fdp/application.yml:ro # ... other volumes fdp-client: - image: fairdata/fairdatapoint-client:1.7.0 + image: fairdata/fairdatapoint-client:1.8.0 ports: - 80:80 environment: diff --git a/docs/deployment/local-deployment.rst b/docs/deployment/local-deployment.rst index 686d1e7..0bdcd42 100644 --- a/docs/deployment/local-deployment.rst +++ b/docs/deployment/local-deployment.rst @@ -14,10 +14,10 @@ Here is an example of the simplest `Docker Compose `_ vocabulary introduces extensions to the dash:editor dash:TextFieldEditor ; ] -By adding a ``dash:viewer`` statement, the user interface is instructed to show the property value when the resource metadata is displayed. Removing a ``dash:viewer`` statement will instruct the user interface will not render the property value at all. The value will still be present in the metadata model. The supported set of viewers (version 1.6.0): +By adding a ``dash:viewer`` statement, the user interface is instructed to show the property value when the resource metadata is displayed. Removing a ``dash:viewer`` statement will instruct the user interface will not render the property value at all. The value will still be present in the metadata model. The supported set of viewers: * ``sh:LabelViewer`` * ``sh:URIViewer`` -By adding a ``dash:editor`` statement, the editor form in the user interface will show an edit field for the property. Removing a ``dash:editor`` statement will prevent the property from being edited. This could be intended behaviour for properties that are generated server side. The supported set of editors (version 1.6.0): +By adding a ``dash:editor`` statement, the editor form in the user interface will show an edit field for the property. Removing a ``dash:editor`` statement will prevent the property from being edited. This could be intended behaviour for properties that are generated server side. The supported set of editors: * ``sh:TextFieldEditor`` * ``sh:TextAreaEditor``