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``
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.