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

View File

@ -1,18 +1,20 @@
Welcome to gCat documentation!
=================================================
#############################
Welcome to gCat documentation
#############################
gCat is a RESTful application which exposes operations ...
See the available REST-API on `its API docs <../api-docs/index.html>`_.
**********
Base URL
==================
**********
In the production environment, its current value is https://api.d4science.org/gcat
*************
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.
@ -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
*******
Service
==================
*******
You can call the methods of the Web Service by writing your own REST client application or using existing REST client plugins.
=============
HTTP Statuses
------------------
=============
Any successful operation returns *200 OK* HTTP status code.
The create operation returns *201 Created*.
Instead, the operations do not provide any content return *204 No Content*.
A Background operation returns *202 Accepted*.
Any 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:
@ -55,8 +61,10 @@ Please use this checklist before reporting an error:
* indicate how to replicate the error;
* indicate the time when the error occurred (this simplifies identifying the issue).
============
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.
@ -108,7 +116,7 @@ gCat is a pure RESTful service. It uses standard HTTP Methods to perform a listi
About URL
'''''''''
*********
The presented URL uses the following convention:
@ -117,7 +125,7 @@ The presented URL uses the following convention:
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"
@ -128,9 +136,8 @@ About Safety and Idempotency properties
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);
* 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``.
============
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.
===========
Collections
------------------
===========
The following collections are available to any user.
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>`_;
=====
Roles
------------------
=====
Any user has one or more roles in the catalogue.
The VRE Manager can only assign roles.
@ -216,9 +225,9 @@ Catalogue-Moderator:
.. TIP::
Please note that not all catalogues are moderated.
********************
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.
@ -341,9 +350,9 @@ The following table summarises the addressee of the notification for any action.
***********
Java Client
==================
***********
We provide the following Java Client out-of-the-box.