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

Trying to fix headers

This commit is contained in:
Luca Frosini 2022-09-21 11:24:15 +02:00
parent 1756db032f
commit 8252055126
1 changed files with 37 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
docs/index.rst
View File

@ -1,18 +1,20 @@
Welcome to gCat documentation! #############################
================================================= Welcome to gCat documentation
#############################
gCat is a RESTful application which exposes operations ... gCat is a RESTful application which exposes operations ...
See the available REST-API on `its API docs <../api-docs/index.html>`_. See the available REST-API on `its API docs <../api-docs/index.html>`_.
Base URL **********
================== Base URL
**********
In the production environment, its current value is https://api.d4science.org/gcat In the production environment, its current value is https://api.d4science.org/gcat
*************
Authorization Authorization
================== *************
D4Science adopts state-of-the-art industry standards for authentication and authorization. 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. Specifically, the implementation fully adopts `OIDC (OpenID Connect) <https://openid.net/connect>`_ for authentication and UMA 2 (User-Managed Authorization) for authorization flows.
@ -20,19 +22,23 @@ Specifically, the implementation fully adopts `OIDC (OpenID Connect) <https://op
Obtain your Bearer token here: https://dev.d4science.org/how-to-access-resources Obtain your Bearer token here: https://dev.d4science.org/how-to-access-resources
*******
Service 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 own REST client application or using existing REST client plugins.
=============
HTTP Statuses HTTP Statuses
------------------ =============
Any successful operation returns *200 OK* HTTP status code. Any successful operation returns *200 OK* HTTP status code.
The create operation returns *201 Created*. The create operation returns *201 Created*.
Instead, the operations do not provide any content return *204 No Content*. Any Background operation returns *202 Accepted*.
A Background operation returns *202 Accepted*. Any operation which does not provide any content return *204 No Content*.
The most common error status a client can obtain are: The most common error status a client can obtain are:
@ -55,8 +61,10 @@ Please use this checklist before reporting an error:
* indicate how to replicate the error; * indicate how to replicate the error;
* indicate the time when the error occurred (this simplifies identifying the issue). * indicate the time when the error occurred (this simplifies identifying the issue).
============
HTTP Methods HTTP Methods
------------------ ============
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. 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.
@ -105,10 +113,10 @@ gCat is a pure RESTful service. It uses standard HTTP Methods to perform a listi
We share the same vision. For this reason, gCat does not provide server-side idempotency for DELETE and PURGE operations. 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 About URL
''''''''' *********
The presented URL uses the following convention: The presented URL uses the following convention:
@ -117,7 +125,7 @@ The presented URL uses the following convention:
About Safety and Idempotency properties About Safety and Idempotency properties
''''''''' ***************************************
* A method is *Safe* if it does not produce any side effects. * 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" "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"
@ -128,9 +136,8 @@ About Safety and Idempotency properties
You can find more information about HTTP Methods at `<https://restfulapi.net/http-methods/>`_ You can find more information about HTTP Methods at `<https://restfulapi.net/http-methods/>`_
Uncommon HTTP Methods
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); * 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 service which requires this action
@ -138,8 +145,9 @@ Uncommon HTTP Methods:
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``. 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 an indication of the interesting content type. Any request must contain an indication of the interesting content type.
@ -159,9 +167,9 @@ The service accepts and returns only JSON objects.
`Profile Collection <../api-docs/resource\_Profile.html>`_ instead can be manipulated in XML only. `Profile Collection <../api-docs/resource\_Profile.html>`_ instead can be manipulated in XML only.
===========
Collections Collections
------------------ ===========
The following collections are available to any user. The following collections are available to any user.
Catalogue-Editor or above can invoke Non-safe methods only. Catalogue-Editor or above can invoke Non-safe methods only.
@ -185,8 +193,9 @@ The following collections are available for Catalogue-Admins or above only:
An overview 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 Roles
------------------ =====
Any user has one or more roles in the catalogue. Any user has one or more roles in the catalogue.
The VRE Manager can only assign roles. The VRE Manager can only assign roles.
@ -216,9 +225,9 @@ Catalogue-Moderator:
.. TIP:: .. TIP::
Please note that not all catalogues are moderated. Please note that not all catalogues are moderated.
********************
Moderated Catalogues Moderated Catalogues
================== ********************
Any catalogues can be declared as moderated. 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.
@ -341,9 +350,9 @@ The following table summarises the addressee of the notification for any action.
***********
Java Client Java Client
================== ***********
We provide the following Java Client out-of-the-box. We provide the following Java Client out-of-the-box.