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

Fixed typos and grammar

This commit is contained in:
Luca Frosini 2024-04-16 14:48:47 +02:00
parent 322a9509fb
commit 638823062a
1 changed files with 19 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
docs/index.rst
View File

@ -1,9 +1,8 @@
***********************************************************
Welcome to gCube Catalogue Service (aka gCat) documentation
***********************************************************
gCat is a RESTful application which exposes operations via REST-API.
gCat is a RESTful application that exposes operations via REST-API.
See the available `REST-API docs <../api-docs/index.html>`_.
@ -25,23 +24,23 @@ 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.
You can call the methods of the Web Service by writing your REST client application or using existing REST client plugins.
HTTP Statuses
-------------
Any successful operation returns *200 OK* HTTP status code.
Any successful operation returns a *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*.
Any operation that does not provide any content returns *204 No Content*.
The most common error status a client can obtain are:
The most common error statuses 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>`_;
* **401 Unauthorized** used to indicate that the client does not provide the authorization token in the HTTP Header or the client does not have 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>`_;
@ -55,7 +54,7 @@ If you get a *500 Internal Server Error*, please report it in the `gCube ticketi
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;
* The failure could be temporal due to a network error, a 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).
@ -104,12 +103,12 @@ gCat is a pure RESTful service. It uses standard HTTP Methods to perform a listi
.. [#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 server should inform the client if the delete operation succeeded because the resource was 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
.. [#Allamaraju] Allamaraju S. RESTful Web Services Cookbook: Solutions for Improving Scalability and Simplicity. O’Reilly. first ed. 2010
About URL
@ -128,7 +127,7 @@ 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.
* A method is *Idempotent* if the same operation repeated multiple times has the same side effect as 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>`_.
@ -138,7 +137,7 @@ 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
* PURGE method is not a standard but is widely used in services that require 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``.
@ -225,12 +224,12 @@ 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.
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.
The item is 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**:
@ -250,7 +249,7 @@ To present the moderation operations, we use the following convention:
``initial_state`` can be ``none``, meaning the item does not exist.
The following are the allowed moderation operation on an item
The following are the allowed moderation operations on an item
``none`` ---**create** (*Author*)---> ``pending``
@ -263,14 +262,14 @@ The following are the allowed moderation operation on an item
``approved`` ---**update** (*Author*)---> ``pending``
Please check the table below whcih summarise the item collection operation and the allowed users/roles.
Please check the table below that summarises the item collection operation 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:
Messages can be sent both with an action which changes the status of the item or as an explicit action which does not change the status of the item:
``pending`` ---**message** (*Author OR Catalogue-Moderator*)---> ``pending``
@ -280,7 +279,7 @@ Messages can be sent both with an action which changes the status of the item or
The following table summarize the allowed/forbidden operations depending on: the role of the user and the state of the item.
The following table summarizes the allowed/forbidden operations depending on the role of the user and the state of the item.
.. table::
@ -478,7 +477,7 @@ The service can be discovered in the gCore IS as gCore Endpoint with the followi
<ServiceName>gcat</ServiceName>
The service can be discovered in the Facet Based IS as EService with the following json query:
The service can be discovered in the Facet-Based IS as EService with the following JSON query:
.. code:: json
@ -501,7 +500,7 @@ The service can be discovered in the Facet Based IS as EService with the followi
Service Maven Coordinates
=========================
The maven coordinates of gCat service are:
The maven coordinates of the gCat service are:
.. code:: xml