Added files to create sphinx documentation
This commit is contained in:
parent
1b0d66d984
commit
6939a9622a
|
|
@ -0,0 +1,20 @@
|
|||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# This file only contains a selection of the most common options. For a full
|
||||
# list see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
# -- Path setup --------------------------------------------------------------
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#
|
||||
# import os
|
||||
# import sys
|
||||
# sys.path.insert(0, os.path.abspath('.'))
|
||||
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = 'gCube Global Record of Stocks and Fisheries (GRSF) Publisher Service'
|
||||
copyright = '2023, Luca Frosini (ISTI-CNR)'
|
||||
author = 'Luca Frosini (ISTI-CNR)'
|
||||
|
||||
# The full version, including alpha/beta/rc tags
|
||||
release = '1.0.0-SNAPSHOT'
|
||||
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = []
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This pattern also affects html_static_path and html_extra_path.
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = 'sphinxdoc'
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
||||
|
|
@ -0,0 +1,262 @@
|
|||
|
||||
*************************************************************************************
|
||||
Welcome to gCube Global Record of Stocks and Fisheries (GRSF) Publisher documentation
|
||||
*************************************************************************************
|
||||
|
||||
gCube Global Record of Stocks and Fisheries (GRSF) Publisher is a RESTful application which exposes operations via REST-API.
|
||||
|
||||
See the available `REST-API docs <../api-docs/index.html>`_.
|
||||
|
||||
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.
|
||||
`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
|
||||
|
||||
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*.
|
||||
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:
|
||||
|
||||
* **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 provide the authorization token in the HTTP Header or the client 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 exist `<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>`_.
|
||||
|
||||
You can find a complete list of HTTP Status at `<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 and many other temporal issues. For this reason, please retry the request after a certain amount of time before reporting the issue;
|
||||
* indicate how to replicate the error;
|
||||
* indicate the time when the error occurred (this simplifies identifying the issue).
|
||||
|
||||
HTTP Methods
|
||||
------------
|
||||
|
||||
This 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.
|
||||
|
||||
|
||||
.. table::
|
||||
|
||||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||||
| Operation | HTTP Method | URL | Success HTTP Status | Safe | Idempotent |
|
||||
+==============+=============+========================================+=====================+========+============+
|
||||
| Supported | OPTIONS | /{COLLECTION} | 204 No Content | Y | Y |
|
||||
| HTTP Methods | | | [#allow]_ | | |
|
||||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||||
| 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 | | | [#allow]_ | | |
|
||||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||||
| 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 [#del]_ |
|
||||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||||
| Purge | DELETE | /{COLLECTION}/{INSTANCE_ID}?purge=true | 204 No Content | N | N [#del]_ |
|
||||
+ +-------------+----------------------------------------+---------------------+--------+------------+
|
||||
| | PURGE | /{COLLECTION}/{INSTANCE_ID} | 204 No Content | N | N [#del]_ |
|
||||
+--------------+-------------+----------------------------------------+---------------------+--------+------------+
|
||||
|
||||
.. [#allow] Supported HTTP Methods in **Allow** HTTP Header
|
||||
|
||||
.. [#del] DELETE has been defined as idempotent.
|
||||
|
||||
*Allamaraju* [#Allamaraju]_ argues that DELETE idempotency should be accomplished client-side.
|
||||
The server should inform the client if the delete operation 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
|
||||
^^^^^^^^^
|
||||
|
||||
The presented URL uses the following convention:
|
||||
|
||||
* **{COLLECTION}** is the plural name of the entity type;
|
||||
* **{INSTANCE_ID}** is an identification that enables univocally identifying 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 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
|
||||
(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 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.
|
||||
|
||||
The client must specify the **Accept** HTTP Header for any operation returning a result.
|
||||
|
||||
.. code-block:: rest
|
||||
|
||||
Accept: application/json
|
||||
|
||||
For any operation sending content to the service, it is necessary to specify the **Content-Type** HTTP Header.
|
||||
|
||||
.. code-block:: rest
|
||||
|
||||
Content-Type: application/json
|
||||
|
||||
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.
|
||||
|
||||
* `Profile Collection <../api-docs/resource_Profile.html>`_;
|
||||
* `Trash Collection <../api-docs/resource_Trash.html>`_;
|
||||
|
||||
The following collections are available for Catalogue-Admins or above only:
|
||||
|
||||
* `Group Collection <../api-docs/resource_Group.html>`_;
|
||||
* `Organization Collection <../api-docs/resource_Organization.html>`_;
|
||||
* `User Collection <../api-docs/resource_User.html>`_;
|
||||
* `Configuration Collection <../api-docs/resource_Configuration.html>`_.
|
||||
|
||||
An overview of the available collections is available at `<../api-docs/index.html>`_;
|
||||
|
||||
|
||||
Roles
|
||||
-----
|
||||
|
||||
Any user has one or more roles in the catalogue.
|
||||
Only the VRE Manager can assign roles to VRE users.
|
||||
|
||||
|
||||
The service uses the following hierarchic roles:
|
||||
|
||||
**GRSF-Member**:
|
||||
A user with such a role is mainly capable of listing and reading items;
|
||||
|
||||
**GRSF-Editor**:
|
||||
A user with such a role is capable of managing the records and capable of using other safe APIs;
|
||||
|
||||
**GRSF-Admin**:
|
||||
A user with such a role is capable of administrating many aspects of the catalogue;
|
||||
|
||||
**GRSF-Manager**:
|
||||
A user with such a role can use all the APIs exposed by the service except item moderation APIs (e.g. approve, reject, ...).
|
||||
|
||||
|
||||
Another role that is not in the role hierarchy:
|
||||
|
||||
**GRSF-Moderator**:
|
||||
A user with such a role is capable of invoking the item moderation APIs.
|
||||
|
||||
**Methods Result**
|
||||
|
||||
The service exposes `its methods <../api-docs/index.html>`_ using a standard naming approach. Moreover, they accept (in the case of HTTP POST/PUT methods) JSON objects.
|
||||
|
||||
.. IMPORTANT::
|
||||
The result of all methods is always a JSON object as per below:
|
||||
|
||||
.. code:: javascript
|
||||
|
||||
|
||||
|
||||
|
||||
*Inputs are automatically validated before the request is served.*
|
||||
|
||||
|
||||
Service Discovery on IS
|
||||
=======================
|
||||
|
||||
The service can be discovered in the gCore IS as gCore Endpoint with the following parameter:
|
||||
|
||||
.. code:: xml
|
||||
|
||||
<ServiceClass>org.gcube.data-catalogue</ServiceClass>
|
||||
<ServiceName>grsf-publisher</ServiceName>
|
||||
|
||||
|
||||
The service can be discovered in the Facet Based IS as EService with the following json query:
|
||||
|
||||
.. code:: json
|
||||
|
||||
{
|
||||
"@class": "EService",
|
||||
"consistsOf": [
|
||||
{
|
||||
"@class": "IsIdentifiedBy",
|
||||
"target": {
|
||||
"@class": "SoftwareFacet",
|
||||
"group": "org.gcube.data-catalogue",
|
||||
"name": "grsf-publisher"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
|
||||
Service Maven Coordinates
|
||||
=========================
|
||||
|
||||
The maven coordinates of gCat service are:
|
||||
|
||||
.. code:: xml
|
||||
|
||||
<groupId>org.gcube.data-catalogue</groupId>
|
||||
<artifactId>grsf-publisher</artifactId>
|
||||
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
@ECHO OFF
|
||||
|
||||
pushd %~dp0
|
||||
|
||||
REM Command file for Sphinx documentation
|
||||
|
||||
if "%SPHINXBUILD%" == "" (
|
||||
set SPHINXBUILD=sphinx-build
|
||||
)
|
||||
set SOURCEDIR=.
|
||||
set BUILDDIR=_build
|
||||
|
||||
if "%1" == "" goto help
|
||||
|
||||
%SPHINXBUILD% >NUL 2>NUL
|
||||
if errorlevel 9009 (
|
||||
echo.
|
||||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
||||
echo.installed, then set the SPHINXBUILD environment variable to point
|
||||
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
||||
echo.may add the Sphinx directory to PATH.
|
||||
echo.
|
||||
echo.If you don't have Sphinx installed, grab it from
|
||||
echo.https://www.sphinx-doc.org/
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
goto end
|
||||
|
||||
:help
|
||||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
|
||||
:end
|
||||
popd
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE xml>
|
||||
<application mode='online'>
|
||||
<name>${project.artifactId}</name>
|
||||
<group>${project.groupId}</group>
|
||||
<version>${project.version}</version>
|
||||
<description>${project.description}</description>
|
||||
<exclude>/api-docs.*</exclude>
|
||||
<exclude>/docs.*</exclude>
|
||||
</application>
|
||||
Loading…
Reference in New Issue