Adding documentation
This commit is contained in:
parent
1346a198d4
commit
0e2a635bba
|
|
@ -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 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']
|
||||||
|
|
@ -0,0 +1,264 @@
|
||||||
|
---
|
||||||
|
title: Welcome to gCube Resource Manager Service 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)](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
|
||||||
|
------------
|
||||||
|
|
||||||
|
Resource Manager is a pure RESTful service. It uses standard HTTP Methods to perform
|
||||||
|
listing of collections and CRUD (Create Read Update Delete) operations
|
||||||
|
on instances.
|
||||||
|
|
||||||
|
:::{table} Supported operations
|
||||||
|
:align: center
|
||||||
|
:widths: grid
|
||||||
|
|
||||||
|
|
||||||
|
| Operation | HTTP Method | URL | Success HTTP Status | Safe | Idempotent |
|
||||||
|
|-----------|-------------|-----|---------------------|------|------------|
|
||||||
|
| **Supported<br/>HTTP Methods** | OPTIONS | /{COLLECTION} | 204 No Content | Y | Y |
|
||||||
|
| **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<br/>HTTP Methods** | OPTIONS | /{COLLECTION}/{INSTANCE_ID} | 204 No Content | Y | Y |
|
||||||
|
| **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 |
|
||||||
|
| **Purge** | PURGE | /{COLLECTION}/{INSTANCE_ID} | 204 No Content | N | N |
|
||||||
|
| **Purge** | DELETE | /{COLLECTION}/{INSTANCE_ID}?purge=true | 204 No Content | N | N |
|
||||||
|
|
||||||
|
|
||||||
|
### 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.
|
||||||
|
|
||||||
|
``` {.rest}
|
||||||
|
Accept: application/json
|
||||||
|
```
|
||||||
|
|
||||||
|
For any operation sending content to the service, it is necessary to
|
||||||
|
specify the **Content-Type** HTTP Header.
|
||||||
|
|
||||||
|
``` {.rest}
|
||||||
|
Content-Type: application/json
|
||||||
|
```
|
||||||
|
|
||||||
|
The service accepts and returns only JSON objects.
|
||||||
|
|
||||||
|
|
||||||
|
Collections
|
||||||
|
-----------
|
||||||
|
|
||||||
|
The following collections are available
|
||||||
|
|
||||||
|
....
|
||||||
|
|
||||||
|
Roles
|
||||||
|
-----
|
||||||
|
|
||||||
|
Any user has one or more roles in the catalogue. Only the VRE Manager
|
||||||
|
can assign roles to VRE users.
|
||||||
|
|
||||||
|
The catalogue uses the following hierarchic roles:
|
||||||
|
|
||||||
|
**Manager**:
|
||||||
|
|
||||||
|
: .......;
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Java Client
|
||||||
|
===========
|
||||||
|
|
||||||
|
We provide the following Java Client out-of-the-box.
|
||||||
|
|
||||||
|
> ::: {.tip}
|
||||||
|
> ::: {.title}
|
||||||
|
> Tip
|
||||||
|
> :::
|
||||||
|
>
|
||||||
|
> If you\'re coding in Java, it is recommended that you use this Java
|
||||||
|
> Client.
|
||||||
|
> :::
|
||||||
|
|
||||||
|
**Maven Coordinates**
|
||||||
|
|
||||||
|
``` {.xml}
|
||||||
|
<groupId></groupId>
|
||||||
|
<artifactId></artifactId>
|
||||||
|
<version></version>
|
||||||
|
```
|
||||||
|
|
||||||
|
**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}
|
||||||
|
> ::: {.title}
|
||||||
|
> Important
|
||||||
|
> :::
|
||||||
|
>
|
||||||
|
> The result of all methods is always a JSON object as per below:
|
||||||
|
> :::
|
||||||
|
|
||||||
|
|
||||||
|
*Inputs are automatically validated before the request is served.*
|
||||||
|
|
||||||
|
**Usage examples**
|
||||||
|
|
||||||
|
|
||||||
|
Service Discovery on IS
|
||||||
|
=======================
|
||||||
|
|
||||||
|
The service can be discovered in the Facet Based IS as EService with the
|
||||||
|
following json query:
|
||||||
|
|
||||||
|
``` {.json}
|
||||||
|
{
|
||||||
|
"@class": "EService",
|
||||||
|
"consistsOf": [
|
||||||
|
{
|
||||||
|
"@class": "IsIdentifiedBy",
|
||||||
|
"target": {
|
||||||
|
"@class": "SoftwareFacet",
|
||||||
|
"group": "org.gcube.resource-management",
|
||||||
|
"name": "resource-manager"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Service Maven Coordinates
|
||||||
|
=========================
|
||||||
|
|
||||||
|
The maven coordinates of gCat service are:
|
||||||
|
|
||||||
|
``` {.xml}
|
||||||
|
<groupId>org.gcube.resource-management</groupId>
|
||||||
|
<artifactId>resource-manager</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,7 @@
|
||||||
|
name: ${project.artifactId}
|
||||||
|
group: ${project.groupId}
|
||||||
|
version: ${project.version}
|
||||||
|
description: ${project.description}
|
||||||
|
excludes:
|
||||||
|
- path: /docs.*
|
||||||
|
- path: /api-docs.*
|
||||||
|
|
@ -0,0 +1,22 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
|
||||||
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||||
|
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
|
||||||
|
version="4.0">
|
||||||
|
<display-name>Hello World</display-name>
|
||||||
|
<description>
|
||||||
|
A gcube HelloWorld service - smartgears 4
|
||||||
|
</description>
|
||||||
|
<servlet>
|
||||||
|
<servlet-name>HelloWorld</servlet-name>
|
||||||
|
<servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
|
||||||
|
<init-param>
|
||||||
|
<param-name>jersey.config.server.provider.packages</param-name>
|
||||||
|
<param-value>org.gcube.service.helloworld.services</param-value>
|
||||||
|
</init-param>
|
||||||
|
</servlet>
|
||||||
|
<servlet-mapping>
|
||||||
|
<servlet-name>HelloWorld</servlet-name>
|
||||||
|
<url-pattern>/*</url-pattern>
|
||||||
|
</servlet-mapping>
|
||||||
|
</web-app>
|
||||||
Loading…
Reference in New Issue