Adding documentation
This commit is contained in:
parent
66810e67a4
commit
599ce4405b
203
docs/index.rst
203
docs/index.rst
|
|
@ -32,6 +32,111 @@ 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.
|
||||
|
||||
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*.
|
||||
|
||||
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>`_;
|
||||
* **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/>`_
|
||||
|
||||
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;
|
||||
* indicate how to replicate the error;
|
||||
* indicate the time when the error occurred (this simplify the identification of 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.
|
||||
|
||||
|
||||
.. table::
|
||||
|
||||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||||
| Operation | HTTP Method | URL | Success HTTP Status | Safe | Idempotent |
|
||||
+==============+=============+========================================+=====================+========+============+
|
||||
| Supported | OPTIONS | /{COLLECTION} | 204 No Content ‡ | Y | Y |
|
||||
| HTTP Methods | | | | | |
|
||||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||||
| 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 | | | | | |
|
||||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||||
| 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 ‡‡ |
|
||||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||||
| Purge | DELETE | /{COLLECTION}/{INSTANCE_ID}?purge=true | 204 No Content | N | N ‡‡ |
|
||||
+ +-------------+----------------------------------------+---------------------+--------+------------+
|
||||
| | PURGE | /{COLLECTION}/{INSTANCE_ID} | 204 No Content | N | N ‡‡ |
|
||||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||||
|
||||
‡ Supported HTTP Methods in **Allow** HTTP Header
|
||||
|
||||
‡‡ DELETE has been defined as idempotent.
|
||||
|
||||
*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 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:
|
||||
|
||||
* {COLLECTION} is the plural name of the entity type;
|
||||
* {INSTANCE_ID} is an identification which enables to univocally identify 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 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
|
||||
(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``
|
||||
|
||||
Content Type
|
||||
------------------
|
||||
|
||||
|
|
@ -53,86 +158,44 @@ Actually, 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.
|
||||
|
||||
|
||||
HTTP Statuses
|
||||
Collections
|
||||
------------------
|
||||
|
||||
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*.
|
||||
The following collections are available to any users. Non-safe methods can only be invoked by Catalogue Editor
|
||||
|
||||
The most common error status a client can obtain are:
|
||||
* Item Collection;
|
||||
|
||||
* Resource Collection;
|
||||
|
||||
* **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>`_;
|
||||
* **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>`_.
|
||||
* Profile Collection;
|
||||
* Namespace Collection;
|
||||
* License Collection;
|
||||
|
||||
A complete list of HTTP Status can be found here:
|
||||
`<https://httpstatuses.com/>`_
|
||||
The following collections are available only for Catalogue Admin:
|
||||
|
||||
I 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
|
||||
* indicate how to replicate the error
|
||||
* indicate the time when the error occurred (this simplify the identification of 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.
|
||||
* Group Collection;
|
||||
* Organization Collection;
|
||||
* User Collection;
|
||||
* Configuration Collection.
|
||||
|
||||
|
||||
{| class="wikitable"
|
||||
! Operation || HTTP Method || URL || Success HTTP Status || Safe || Idempotent
|
||||
|-
|
||||
| Supported<br />HTTP Methods || OPTIONS || /{COLLECTION} || 204 No Content<br />(Supported HTTP Methods in ''Allow'' HTTP Header) || Y || Y
|
||||
|-
|
||||
| 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<br />HTTP Methods || OPTIONS || /{COLLECTION}/{INSTANCE_ID} || 204 No Content<br />(Supported HTTP Methods in ''Allow'' HTTP Header) || Y || Y
|
||||
|-
|
||||
| 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
|
||||
|-
|
||||
| <span id="delete">Delete</span> || DELETE || /{COLLECTION}/{INSTANCE_ID} || 204 No Content || N || N [[#non_safe_delete| ‡]]
|
||||
|-
|
||||
| Purge || PURGE || /{COLLECTION}/{INSTANCE_ID} || 204 No Content || N || N[[#non_safe_delete| ‡]]
|
||||
|-
|
||||
| Purge || DELETE || /{COLLECTION}/{INSTANCE_ID}?purge=true || 204 No Content || N || N[[#non_safe_delete| ‡]]
|
||||
|}
|
||||
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 is capable of using all the APIs exposed by the service except moderation item 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.
|
||||
|
||||
|
||||
About URL:
|
||||
* {COLLECTION} is the plural name of the entity type;
|
||||
* {INSTANCE_ID} is an identification which enables to univocally identify 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 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 https://tools.ietf.org/html/rfc7231#section-4.2.2].
|
||||
|
||||
[[#delete|‡]] DELETE has been defined as idempotent. <span id="non_safe_delete">Allamaraju</span><ref>Allamaraju S. RESTful Web Services Cookbook: Solutions for Improving Scalability and Simplicity . O’Reilly. first ed. 2010</ref> 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 latter situation should be treated as idempotent by the client. For this reason, gCat does not provide server-side idempotency for DELETE and PURGE operations.
|
||||
|
||||
You can find more information about HTTP Methods at [https://restfulapi.net/http-methods/ https://restfulapi.net/http-methods/]
|
||||
|
||||
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 (e.g. [https://varnish-cache.org/docs/3.0/tutorial/purging.html Varnish], [https://wiki.squid-cache.org/SquidFaq/OperatingSquid#How_can_I_purge_an_object_from_my_cache.3F 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 <pre>purge=true</pre>
|
||||
|
||||
.. TIP::
|
||||
Please note that not all catalogues are moderated.
|
||||
|
||||
Java Client
|
||||
==================
|
||||
|
|
|
|||
Loading…
Reference in New Issue