diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -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) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..02f5c6b --- /dev/null +++ b/docs/conf.py @@ -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'] \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..a500344 --- /dev/null +++ b/docs/index.md @@ -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: + + +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 + ; +- **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 + ; +- **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](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
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
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\" + ; +- 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\" + . + +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 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} + + + +``` + +**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} +org.gcube.resource-management +resource-manager +``` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..153be5e --- /dev/null +++ b/docs/make.bat @@ -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 diff --git a/gcube/extra-resources/WEB-INF/application.yaml b/gcube/extra-resources/WEB-INF/application.yaml new file mode 100644 index 0000000..7db75b7 --- /dev/null +++ b/gcube/extra-resources/WEB-INF/application.yaml @@ -0,0 +1,7 @@ +name: ${project.artifactId} +group: ${project.groupId} +version: ${project.version} +description: ${project.description} +excludes: + - path: /docs.* + - path: /api-docs.* diff --git a/src/main/webapp/WEB-INF/web.xml b/src/main/webapp/WEB-INF/web.xml new file mode 100644 index 0000000..67c7bc7 --- /dev/null +++ b/src/main/webapp/WEB-INF/web.xml @@ -0,0 +1,22 @@ + + + Hello World + + A gcube HelloWorld service - smartgears 4 + + + HelloWorld + org.glassfish.jersey.servlet.ServletContainer + + jersey.config.server.provider.packages + org.gcube.service.helloworld.services + + + + HelloWorld + /* + + \ No newline at end of file