392 lines
21 KiB
ReStructuredText
392 lines
21 KiB
ReStructuredText
|
||
***********************************************************
|
||
Welcome to gCube Catalogue Service (aka gCat) documentation
|
||
***********************************************************
|
||
|
||
gCat is a RESTful application which exposes operations ...
|
||
|
||
See the available REST-API on `its API docs <../api-docs/index.html>`_.
|
||
|
||
Base URL
|
||
========
|
||
|
||
In the production environment, its current value is https://api.d4science.org/gcat
|
||
|
||
|
||
Authorization
|
||
=============
|
||
|
||
D4Science adopts state-of-the-art industry standards for authentication and authorization.
|
||
Specifically, the implementation fully adopts `OIDC (OpenID Connect) <https://openid.net/connect>`_ for authentication and UMA 2 (User-Managed Authorization) for authorization flows.
|
||
`JSON Web Token (JWT) Access token <https://jwt.io/>`_ are used for both authentication and authorization.
|
||
|
||
Obtain your Bearer token here: https://dev.d4science.org/how-to-access-resources
|
||
|
||
Service
|
||
=======
|
||
|
||
You can call the methods of the Web Service by writing your own REST client application or using existing REST client plugins.
|
||
|
||
|
||
HTTP Statuses
|
||
-------------
|
||
|
||
Any successful operation returns *200 OK* HTTP status code.
|
||
The create operation returns *201 Created*.
|
||
Any Background operation returns *202 Accepted*.
|
||
Any operation which does not provide any content return *204 No Content*.
|
||
|
||
|
||
|
||
The most common error status a client can obtain are:
|
||
|
||
* **400 Bad Request** used to indicate a clients error `<https://tools.ietf.org/html/rfc7231#section-6.5.1>`_;
|
||
* **401 Unauthorized** used to indicate that the client does not provide the authorization token in the HTTP Header or the client has not enough right to perform such request `<https://tools.ietf.org/html/rfc7235#section-3.1>`_;
|
||
* **404 Not Found** used to indicate that the requested instance does not exist `<https://tools.ietf.org/html/rfc7231#section-6.5.4>`_;
|
||
* **405 Method Not Allowed** the used HTTP method is not supported for the requested URL `<https://tools.ietf.org/html/rfc7231#section-6.5.5>`_.
|
||
The response contains the *Allow* HTTP Header indicating the supported HTTP method for such URL `<https://tools.ietf.org/html/rfc7231#section-7.4.1>`_;
|
||
* **409 Conflict** the request could not be completed due to a conflict with the current state of the target resource (e.g. the name of the resource already exists) `<https://tools.ietf.org/html/rfc7231#section-6.5.8>`_;
|
||
* **500 Internal Server Error** indicate a server failure `<https://tools.ietf.org/html/rfc7231#section-6.6.1>`_.
|
||
|
||
You can find a complete list of HTTP Status at `<https://httpstatuses.com/>`_
|
||
|
||
If you get a *500 Internal Server Error*, please report it in the `gCube ticketing system <https://support.d4science.org>`_.
|
||
|
||
Please use this checklist before reporting an error:
|
||
|
||
* Replicate the request;
|
||
* The failure could be temporal due to network error, server issue and many other temporal issues. For this reason, please retry the request after a certain amount of time before reporting the issue;
|
||
* indicate how to replicate the error;
|
||
* indicate the time when the error occurred (this simplifies identifying the issue).
|
||
|
||
HTTP Methods
|
||
------------
|
||
|
||
gCat is a pure RESTful service. It uses standard HTTP Methods to perform a listing of collections and CRUD (Create Read Update Delete) operations on instances.
|
||
|
||
|
||
.. table::
|
||
|
||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||
| Operation | HTTP Method | URL | Success HTTP Status | Safe | Idempotent |
|
||
+==============+=============+========================================+=====================+========+============+
|
||
| Supported | OPTIONS | /{COLLECTION} | 204 No Content | Y | Y |
|
||
| HTTP Methods | | | [#allow]_ | | |
|
||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||
| List | GET | /{COLLECTION} | 200 OK | Y | Y |
|
||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||
| Count | GET | /{COLLECTION}?count=true | 200 OK | Y | Y |
|
||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||
| Exists | HEAD | /{COLLECTION} | 204 No Content | Y | Y |
|
||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||
| Create | POST | /{COLLECTION} | 201 Created | N | N |
|
||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||
| Supported | OPTIONS | /{COLLECTION}/{INSTANCE_ID} | 204 No Content | Y | Y |
|
||
| HTTP Methods | | | [#allow]_ | | |
|
||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||
| Exist | HEAD | /{COLLECTION}/{INSTANCE_ID} | 204 No Content | Y | Y |
|
||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||
| Read | GET | /{COLLECTION}/{INSTANCE_ID} | 200 OK | Y | Y |
|
||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||
| Update | PUT | /{COLLECTION}/{INSTANCE_ID} | 200 OK | N | Y |
|
||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||
| Patch | PATCH | /{COLLECTION}/{INSTANCE_ID} | 200 OK | N | Y |
|
||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||
| Delete | DELETE | /{COLLECTION}/{INSTANCE_ID} | 204 No Content | N | N [#del]_ |
|
||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||
| Purge | DELETE | /{COLLECTION}/{INSTANCE_ID}?purge=true | 204 No Content | N | N [#del]_ |
|
||
+ +-------------+----------------------------------------+---------------------+--------+------------+
|
||
| | PURGE | /{COLLECTION}/{INSTANCE_ID} | 204 No Content | N | N [#del]_ |
|
||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||
|
||
.. [#allow] Supported HTTP Methods in **Allow** HTTP Header
|
||
|
||
.. [#del] DELETE has been defined as idempotent.
|
||
|
||
*Allamaraju* [#Allamaraju]_ argues that DELETE idempotency should be accomplished client-side.
|
||
The server should inform the client if the delete operation succeeded because the resource was really deleted or it was not found, i.e., **404 Not Found** error is suggested instead of **204 No Content**.
|
||
The latter situation should be treated as idempotent by the client.
|
||
|
||
We share the same vision. For this reason, gCat does not provide server-side idempotency for DELETE and PURGE operations.
|
||
|
||
.. [#Allamaraju] Allamaraju S. RESTful Web Services Cookbook: Solutions for Improving Scalability and Simplicity . O’Reilly. first ed. 2010
|
||
|
||
|
||
About URL
|
||
^^^^^^^^^
|
||
|
||
The presented URL uses the following convention:
|
||
|
||
* **{COLLECTION}** is the plural name of the entity type;
|
||
* **{INSTANCE_ID}** is an identification that enables univocally identifying the instance in the collection.
|
||
|
||
|
||
About Safety and Idempotency properties
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
|
||
* A method is *Safe* if it does not produce any side effects.
|
||
"This does not prevent an implementation from including behaviour that is potentially harmful, that is not entirely read-only, or that causes side effects while invoking a safe method"
|
||
`<https://tools.ietf.org/html/rfc7231#section-4.2.1>`_;
|
||
* A method is *Idempotent* if the same operation repeated multiple times has the same side effect than using it one time.
|
||
"repeating the request will have the same intended effect, even if the original request succeeded, though the response might differ"
|
||
`<https://tools.ietf.org/html/rfc7231#section-4.2.2>`_.
|
||
|
||
You can find more information about HTTP Methods at `<https://restfulapi.net/http-methods/>`_
|
||
|
||
Uncommon HTTP Methods
|
||
^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
* PATCH method allows to perform a differential update (i.e. an update which provides only the differences and not the whole new representation);
|
||
* PURGE method is not a standard but is widely used in service which requires this action
|
||
(e.g. `Varnish <https://varnish-cache.org/docs/3.0/tutorial/purging.html>`_, `Squid <https://wiki.squid-cache.org/SquidFaq/OperatingSquid#How_can_I_purge_an_object_from_my_cache.3F>`_).
|
||
gCat provides support for this method, but to support a wider range of clients, it also provides the Purge action via *DELETE* with the additional get parameter ``purge=true``.
|
||
|
||
|
||
Content-Type
|
||
------------
|
||
|
||
Any request must contain an indication of the interesting content type.
|
||
|
||
The client must specify the **Accept** HTTP Header for any operation returning a result.
|
||
|
||
.. code-block:: rest
|
||
|
||
Accept: application/json
|
||
|
||
For any operation sending content to the service, it is necessary to specify the **Content-Type** HTTP Header.
|
||
|
||
.. code-block:: rest
|
||
|
||
Content-Type: application/json
|
||
|
||
The service accepts and returns only JSON objects.
|
||
|
||
`Profile Collection <../api-docs/resource\_Profile.html>`_ instead can be manipulated in XML only.
|
||
|
||
Collections
|
||
-----------
|
||
|
||
The following collections are available to any user.
|
||
Catalogue-Editor or above can invoke Non-safe methods only.
|
||
|
||
* `Item Collection <../api-docs/resource_Item.html>`_;
|
||
|
||
* `Resource Collection <../api-docs/resource_Resource.html>`_;
|
||
|
||
* `Profile Collection <../api-docs/resource_Profile.html>`_;
|
||
* `Namespace Collection <../api-docs/resource_Namespace.html>`_;
|
||
* `License Collection <../api-docs/resource_License.html>`_;
|
||
* `Trash Collection <../api-docs/resource_Trash.html>`_;
|
||
|
||
The following collections are available for Catalogue-Admins or above only:
|
||
|
||
* `Group Collection <../api-docs/resource_Group.html>`_;
|
||
* `Organization Collection <../api-docs/resource_Organization.html>`_;
|
||
* `User Collection <../api-docs/resource_User.html>`_;
|
||
* `Configuration Collection <../api-docs/resource_Configuration.html>`_.
|
||
|
||
An overview of the available collections is available at `<../api-docs/index.html>`_;
|
||
|
||
|
||
Roles
|
||
-----
|
||
|
||
Any user has one or more roles in the catalogue.
|
||
The VRE Manager can only assign roles.
|
||
|
||
|
||
The catalogue uses the following hierarchic roles:
|
||
|
||
**Catalogue-Member**:
|
||
A user with such a role is mainly capable of listing and reading items;
|
||
|
||
**Catalogue-Editor**:
|
||
A user with such a role is capable of managing the items he/she creates and capable of using other safe APIs;
|
||
|
||
**Catalogue-Admin**:
|
||
A user with such a role is capable of administrating many aspects of the catalogue;
|
||
|
||
**Catalogue-Manager**:
|
||
A user with such a role can use all the APIs exposed by the service except item moderation APIs (e.g. approve, reject, ...).
|
||
|
||
|
||
Another role that is not in the role hierarchy:
|
||
|
||
Catalogue-Moderator:
|
||
A user with such a role is capable of invoking the item moderation APIs.
|
||
|
||
|
||
.. TIP::
|
||
Please note that not all catalogues are moderated.
|
||
|
||
Moderated Catalogues
|
||
====================
|
||
|
||
|
||
Any catalogues can be declared as moderated.
|
||
This means that, a **Catalogue-Moderator** must approve any submitted items to make them available to the other users of the catalogue.
|
||
|
||
In a moderated catalogue, an item can be in the following states:
|
||
|
||
**pending**:
|
||
The item published by any allowed author (a Catalogue-Editor or above) but not available to the other users of the catalogue.
|
||
A Catalogue-Moderator has to approve or reject it;
|
||
|
||
**approved**:
|
||
A Catalogue-Moderator has approved the item published by any allowed users;
|
||
|
||
**rejected**:
|
||
A Catalogue-Moderator has rejected the item published by any allowed users.
|
||
|
||
|
||
|
||
The following are the moderation operations that an allowed user can perform on an item.
|
||
To present the moderation operations, we use the following convention:
|
||
|
||
``initial_state`` ---**operation** (*User/Role performing the operation*)---> ``final_state``
|
||
|
||
|
||
``initial_state`` can be ``none``, meaning the item does not exist.
|
||
|
||
|
||
The following are the allowed moderation operation on an item
|
||
|
||
``none`` ---**create** (*Author*)---> ``pending``
|
||
|
||
``pending`` ---**reject** (*Catalogue-Moderator*)---> ``rejected``
|
||
|
||
``pending`` ---**approve** (*Catalogue-Moderator*)---> ``approved``
|
||
|
||
``rejected`` ---**update** (*Author*)---> ``pending``
|
||
|
||
``approved`` ---**update** (*Author*)---> ``pending``
|
||
|
||
|
||
Please check the table below whcih summarise the item collection opration and the allowed users/roles.
|
||
|
||
In a moderated catalogue, both the Catalogue-Moderators and the item author can send messages to
|
||
discuss the approval process of the item. The messages are related to a specific item.
|
||
Any Catalogue-Moderators receive a message sent by an Author.
|
||
The author receives a message sent by a Catalogue-Moderator as well as the other Catalogue-Moderators (if any).
|
||
|
||
Messages can be sent both with an action which changes the status of the item or as explicit action which does not change the status of the item:
|
||
|
||
``pending`` ---**message** (*Author OR Catalogue-Moderator*)---> ``pending``
|
||
|
||
``rejected`` ---**message** (*Author OR Catalogue-Moderator*)---> ``rejected``
|
||
|
||
``approved`` ---**message** (*Author OR Catalogue-Moderator*)---> ``approved``
|
||
|
||
|
||
|
||
The following table summarize the allowed/forbidden operations depending on: the role of the user and the state of the item.
|
||
|
||
.. table::
|
||
|
||
+-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+
|
||
| Operation | Item State | Roles |
|
||
+ + +----------------------+--------------------------+------------------------------------------+-------------------+
|
||
| | | Catalogue Moderator | Catalogue Admin/Manager | Catalogue Editor | Catalogue Member |
|
||
+=====================================+=============+======================+==========================+==========================================+===================+
|
||
| List | Yes all states | Yes all states | Yes only approved - All states if Author | Yes only approved |
|
||
+-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+
|
||
| Count | Yes all states | Yes all states | Yes only approved - All states if Author | Yes only approved |
|
||
+-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+
|
||
| Create | 403 Forbidden | Yes -> Pending | Yes -> Pending | 403 Forbidden |
|
||
+-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+
|
||
| Read | Yes all states | Yes all states | Yes only approved - All states if Author | Yes only approved |
|
||
+-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+
|
||
| Update | Pending | Yes -> Pending | 403 Forbidden | Yes if Author -> Pending | 403 Forbidden |
|
||
+ +-------------+----------------------+--------------------------+------------------------------------------+-------------------+
|
||
| | Rejected | Yes -> Pending | 403 Forbidden | Yes if Author -> Pending | 403 Forbidden |
|
||
+ +-------------+----------------------+--------------------------+------------------------------------------+-------------------+
|
||
| | Approved | 403 Forbidden | Yes -> Approved | Yes if Author -> Pending | 403 Forbidden |
|
||
+-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+
|
||
| Delete/Purge | Pending | Yes | Yes | Yes if Author | 403 Forbidden |
|
||
+ +-------------+----------------------+--------------------------+------------------------------------------+-------------------+
|
||
| | Rejected | Yes | Yes | Yes if Author | 403 Forbidden |
|
||
+ +-------------+----------------------+--------------------------+------------------------------------------+-------------------+
|
||
| | Approved | 403 Forbidden | Yes | Yes if Author | 403 Forbidden |
|
||
+-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+
|
||
| Approve a pending item | Yes | 403 Forbidden | 403 Forbidden | 403 Forbidden |
|
||
+-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+
|
||
| Reject a pending item | Yes | 403 Forbidden | 403 Forbidden | 403 Forbidden |
|
||
+-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+
|
||
| Message about an item | Yes | Yes if Author | Yes if Author | 403 Forbidden |
|
||
+-------------------------------------+-------------+----------------------+--------------------------+------------------------------------------+-------------------+
|
||
|
||
|
||
The Moderation process has associated notification to authors and Catalogue-Moderators.
|
||
Please note that the user who has acted is not self-notified, e.g.
|
||
approve operation made by a Catalogue-Moderator notifies the item author and the other Catalogue-Moderators of the VRE.
|
||
|
||
The following table summarises the addressee of the notification for any action.
|
||
|
||
|
||
.. table::
|
||
|
||
+------------+-------------------------+-----------------+
|
||
| Operation | Notified user/role |
|
||
+ +-------------------------+-----------------+
|
||
| | Catalogue-Moderators | Author |
|
||
+============+=========================+=================+
|
||
| Create | Yes | No |
|
||
+------------+-------------------------+-----------------+
|
||
| Update | Yes | Yes |
|
||
+------------+-------------------------+-----------------+
|
||
| Approve | Yes + Social Post if enabled for the VRE |
|
||
+------------+-------------------------+-----------------+
|
||
| Reject | Yes | Yes |
|
||
+------------+-------------------------+-----------------+
|
||
| Message | Yes | Yes |
|
||
+------------+-------------------------+-----------------+
|
||
|
||
|
||
|
||
Java Client
|
||
===========
|
||
|
||
We provide the following Java Client out-of-the-box.
|
||
|
||
.. TIP::
|
||
If you're coding in Java, it is recommended that you use this Java Client.
|
||
|
||
**Maven Coordinates**
|
||
|
||
.. code:: xml
|
||
|
||
<groupId>org.gcube.data-catalogue</groupId>
|
||
<artifactId>gcat-client</artifactId>
|
||
<version>[2.2.0, 3.0.0-SNAPSHOT)</version>
|
||
|
||
**Methods Result**
|
||
|
||
The service exposes `its methods <../api-docs/index.html>`_ using a standard naming approach. Moreover, they accept (in the case of HTTP POST/PUT methods) JSON objects.
|
||
|
||
.. IMPORTANT::
|
||
The result of all methods is always a JSON object as per below:
|
||
|
||
.. code:: javascript
|
||
|
||
{
|
||
....
|
||
}
|
||
|
||
*Inputs are automatically validated before the request is served.*
|
||
|
||
|
||
**Usage examples**
|
||
|
||
- Example 1
|
||
|
||
.. code:: java
|
||
|
||
import org.gcube.gcat.client.Item;
|
||
|
||
// count item number
|
||
Item item = new Item();
|
||
int count = item.count();
|
||
...
|
||
|