diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d4bb2cb..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# 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) diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 02f5c6b..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,54 +0,0 @@ -# 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 Resource Manager Service' -copyright = '2024, Luca Frosini (ISTI-CNR)' -author = 'Luca Frosini (ISTI-CNR)' - -# The full version, including alpha/beta/rc tags -release = '1.0.0' - - -# -- 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'] \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 3612e31..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,261 +0,0 @@ -*********************************************************** -Welcome to gCube Catalogue Service (aka gCat) documentation -*********************************************************** - -Resource Manager Service is a RESTful application which exposes operations via REST-API. - -See the available `REST-API docs <../api-docs/index.html>`_. - -Base URL -======== - -In the production environment, its current value is ... - - -Authorization -============= - -D4Science adopts state-of-the-art industry standards for authentication and authorization. -Specifically, the implementation fully adopts `OIDC (OpenID Connect) `_ for authentication and UMA 2 (User-Managed Authorization) for authorization flows. -`JSON Web Token (JWT) Access token `_ 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 REST client application or using existing REST client plugins. - - -HTTP Statuses -------------- - -Any successful operation returns a *200 OK* HTTP status code. -The create operation returns *201 Created*. -Any Background operation returns *202 Accepted*. -Any operation that does not provide any content returns *204 No Content*. - - - -The most common error statuses a client can obtain are: - -* **400 Bad Request** used to indicate a clients error ``_; -* **401 Unauthorized** used to indicate that the client does not provide the authorization token in the HTTP Header or the client does not have enough right to perform such request ``_; -* **404 Not Found** used to indicate that the requested instance does not exist ``_; -* **405 Method Not Allowed** the used HTTP method is not supported for the requested URL ``_. - The response contains the *Allow* HTTP Header indicating the supported HTTP method for such URL ``_; -* **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) ``_; -* **500 Internal Server Error** indicate a server failure ``_. - -You can find a complete list of HTTP Status at ``_ - -If you get a *500 Internal Server Error*, please report it in the `gCube ticketing system `_. - -Please use this checklist before reporting an error: - -* Replicate the request; -* The failure could be temporal due to a network error, a 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 ------------- - -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. - - -.. 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 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" - ``_; -* A method is *Idempotent* if the same operation repeated multiple times has the same side effect as using it one time. - "repeating the request will have the same intended effect, even if the original request succeeded, though the response might differ" - ``_. - -You can find more information about HTTP Methods at ``_ - -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 services that require this action - (e.g. `Varnish `_, `Squid `_). - 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 ... - - - -An overview of the available collections is available at `<../api-docs/index.html>`_; - - -Roles ------ - -Any user has one or more roles in the catalogue. - - -Java Client -=========== - -We provide the following Java Client out-of-the-box. - - .. TIP:: - If you're coding in Java, it is recommended that you use this Java Client. - -**Maven Coordinates** - -.. code:: xml - - org.gcube.resource-management - resource-manager-client - [1.0.0-SNAPSHOT, 2.0.0-SNAPSHOT) - -**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.* - - -**Usage examples** - -- Example 1 - -.. code:: java - - import org.gcube.gcat.client.Item; - - // count item number - Item item = new Item(); - int count = item.count(); - ... - - - -Service Discovery on IS -======================= - -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.resource-management", - "name": "resource-manager" - } - } - ] - } - - - -Service Maven Coordinates -========================= - -The maven coordinates of the gCat service are: - -.. code:: xml - - org.gcube.resource-management - resource-manager - \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 153be5e..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@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