diff --git a/docs/index.rst b/docs/index.rst index 9d03a81..9426bfb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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) `_ for authentication and UMA 2 (User Managed Authorization) for authorization flows. +Specifically, the implementation fully adopts `OIDC (OpenID Connect) `_ for authentication and UMA 2 (User-Managed Authorization) for authorization flows. `JSON Web Token (JWT) Access token `_ 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 ``_; -* **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 ``_; -* **404 Not Found** used to indicate that the requested instance does not exists ``_; +* **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 ``_; +* **404 Not Found** used to indicate that the requested instance does not exist ``_; * **405 Method Not Allowed** the used HTTP method is not supported for the requested URL ``_. The response contains the *Allow* HTTP Header indicating the supported HTTP method for such URL ``_; * **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) ``_; * **500 Internal Server Error** indicate a server failure ``_. -A complete list of HTTP Status can be found here: -``_ +You can find a complete list of HTTP Status at ``_ -If you get a *500 Internal Server Error* please report it in the `gCube ticketing system ``_. +If you get a *500 Internal Server Error*, please report it in the `gCube ticketing system ``_. 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 ``_, `Squid `_). - 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: