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
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.
*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 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
* 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"
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``
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).
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:
``pending`` ---**message** (*Author OR Catalogue-Moderator*)---> ``pending``
``rejected`` ---**message** (*Author OR Catalogue-Moderator*)---> ``rejected``
``approved`` ---**message** (*Author OR Catalogue-Moderator*)---> ``approved``
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.