gCubeSystem
/
gcat
16
0
Fork 0
Code Issues Pull Requests Releases 13 Wiki Activity

Reviewed english

This commit is contained in:
Luca Frosini 2022-09-16 18:01:30 +02:00
parent 57c12a9303
commit d80fa8d303
1 changed files with 48 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
docs/index.rst
View File

@ -15,7 +15,7 @@ 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.
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
@ -24,39 +24,37 @@ Obtain your Bearer token here: https://dev.d4science.org/how-to-access-resources
Service
==================
The methods of the Web Service can be called by writing your own REST client application or by using already existing REST client plugins.
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* status code except for create operation which return *201 Created* or for the operations which do not provide any content and returns *204 No Content*.
Any successful operation returns *200 OK* status code. The create operation returns *201 Created*. Instead, the operations do 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 provided the gcube-token HTTP Header or the clinet 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 exists `<https://tools.ietf.org/html/rfc7231#section-6.5.4>`_;
* **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>`_.
A complete list of HTTP Status can be found here:
`<https://httpstatuses.com/>`_
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>`_.
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 so please retry the request after a certain amount of time;
* 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 simplify the identification of the issue).
* indicate the time when the error occurred (this simplifies identifying the issue).
HTTP Methods
------------------
To be RESTful compliant, gCat uses standard HTTP Methods to perform a listing of collections and CRUD (Create Read Update Delete) operations on instances.
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::
@ -98,7 +96,7 @@ To be RESTful compliant, gCat uses standard HTTP Methods to perform a listing of
.. [#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 a delete 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 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.
@ -112,7 +110,7 @@ About URL
The presented URL uses the following convention:
* **{COLLECTION}** is the plural name of the entity type;
* **{INSTANCE_ID}** is an identification which enables to univocally identify the instance in the collection.
* **{INSTANCE_ID}** is an identification that enables univocally identifying the instance in the collection.
About Safety and Idempotency properties
@ -131,18 +129,18 @@ You can find more information about HTTP Methods at `<https://restfulapi.net/htt
Uncommon HTTP Methods:
'''''''''
* PATCH method allows to perform a differential update (i.e. an update which provide only the differences and not the whole new representation);
* PURGE method is not a standard but is a widely used in service which requires this action
* 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 provide 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``
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
Content-Type
------------------
Any request must contain the indication of the interested content type.
Any request must contain an indication of the interesting content type.
For any operation returning a result, the client must specify the **Accept** HTTP Header.
The client must specify the **Accept** HTTP Header for any operation returning a result.
.. code-block:: rest
@ -154,15 +152,16 @@ For any operation sending content to the service, it is necessary to specify the
Content-Type: application/json
Actually, the service accepts and returns only JSON objects.
The service accepts and returns only JSON objects.
Except for a `Profile Collection <../api-docs/resource\_Profile.html>`_ which must be manipulated in in XML.
`Profile Collection <../api-docs/resource\_Profile.html>`_ instead can be manipulated in XML only.
Collections
------------------
The following collections are available to any users. Non-safe methods can only be invoked by Catalogue-Editor or above.
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>`_;
@ -173,42 +172,42 @@ The following collections are available to any users. Non-safe methods can only
* `License Collection <../api-docs/resource_License.html>`_;
* `Trash Collection <../api-docs/resource_Trash.html>`_;
The following collections are available only for Catalogue-Admins or above:
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 overwiew of the available collections is available at `<../api-docs/index.html>`_;
An overview of the available collections is available at `<../api-docs/index.html>`_;
Roles
------------------
Any user has one or more role in the catalogue.
Roles can only be assigned by the VRE Manager.
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;
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;
A user with such a role is capable of managing the items they create and capable of using other safe APIs;
Catalogue-Admin:
a user with such a role is capable of administrating many aspects of the catalogue;
A user with such a role is capable of administrating many aspects of the catalogue;
Catalogue-Manager:
a user with such a role is capable of using all the APIs exposed by the service except moderation item APIs (i.e. approve, reject).
A user with such a role can use all the APIs exposed by the service except item moderation APIs (i.e. 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.
A user with such a role is capable of invoking the item moderation APIs.
.. TIP::
@ -219,31 +218,31 @@ Moderated Catalogues
==================
Any catalogues can be declared as moderated.
In such a case any submitted items must be approved by a Catalogue-Moderator.
In such a case, 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 users and still not Catalogue-Moderator;
The item published by any allowed users but no Catalogue-Moderator has decided to approve or reject it;
approved:
the item published by any allowed users and rejected by a Catalogue-Moderator;
A Catalogue-Moderator has approved the item published by any allowed users;
rejected:
the item published by any allowed users and approved by a Catalogue-Moderator.
A Catalogue-Moderator has rejected the item published by any allowed users.
In the following are presented the moderation operations an allowed user can perform to an item.
To present the moderation operation the following convenction is used:
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 perfoming the operation*)---> ``final_state``
``initial_state`` ---**operation** (*User/Role performing the operation*)---> ``final_state``
``initial_state`` can be ``none`` which means that the item does not exists.
``initial_state`` can be ``none``, meaning the item does not exist.
The following are the allowed moderation operation on a item in a and the
The following are the allowed moderation operation on an item in a and the
``none`` ---**create** (*Author*)---> ``pending``
@ -257,13 +256,13 @@ The following are the allowed moderation operation on a item in a and the
``approved`` ---**update** (*Author*)---> ``pending``
In a moderated catalogue both the Catalogue-Moderators and the item author can send messages to
discuss about the approval process of the item. The message are related to a specific item.
A message sent by an Author is received by any Catalogue-Moderators.
A message sent by a Catalogue-Moderator is received by the author as weel as the other Catalogue-Moderators (if any).
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 together with an action which change the status of the item or as explicit action which does not change the status of the item:
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``
@ -280,7 +279,7 @@ 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.
If you're coding in Java, it is recommended that you use this Java Client.
**Maven Coordinates**
@ -292,7 +291,7 @@ We provide the following Java Client out-of-the-box.
**Methods Result**
The service exposes `its methods <../api-docs/index.html>`_ using a standard naming approach. Moreover, they accept (in case of http POST/PUT methods) JSON objects.
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: