From c60d99381d5c0f02bf38ce659fe3e1ac59f3f091 Mon Sep 17 00:00:00 2001 From: Luca Frosini Date: Mon, 26 Sep 2022 17:58:52 +0200 Subject: [PATCH] Improving documentation --- docs/index.rst | 47 +++---- src/main/java/org/gcube/gcat/rest/Item.java | 145 +++++++++++++++++++- 2 files changed, 164 insertions(+), 28 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 205bcaf..4bc7a59 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,20 +1,19 @@ -############################# +============================= 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 -********** +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) `_ for authentication and UMA 2 (User-Managed Authorization) for authorization flows. @@ -22,16 +21,14 @@ Specifically, the implementation fully adopts `OIDC (OpenID Connect) `_ 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 @@ -145,9 +142,8 @@ 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. @@ -167,9 +163,8 @@ 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. @@ -193,9 +188,8 @@ 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. @@ -225,9 +219,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. @@ -350,9 +344,8 @@ The following table summarises the addressee of the notification for any action. -*********** Java Client -*********** +=========== We provide the following Java Client out-of-the-box. diff --git a/src/main/java/org/gcube/gcat/rest/Item.java b/src/main/java/org/gcube/gcat/rest/Item.java index bb23928..6a69cb8 100644 --- a/src/main/java/org/gcube/gcat/rest/Item.java +++ b/src/main/java/org/gcube/gcat/rest/Item.java @@ -231,7 +231,150 @@ public class Item extends REST implements org.gcube.gcat.api.interf } - + /** + * @requestExample {"test":"test"} + * @responseExample {"test":"test"} + * + * The create API allows to create an item. + * + * An Item is mainly described by the following attributes (* indicate mandatory attributes): + * + * + *
+ *
name* (string)
+ *
+ * the name of the new item, must be between 2 and 100 characters long + * and contain only lowercase alphanumeric characters, '-' and '_'; + *
+ * + * + *
title (string)
+ *
+ * If not specified it assumes the same value of name attribute. + * The title of the item; + *
+ * + *
maintainer (string)
+ *
the name of the item’s maintainer;
+ * + *
maintainer_email (string)
+ *
the email address of the item’s maintainer;
+ * + *
license_id* (string)
+ *
the id of the item’s license, use License listing API to get available values;
+ * + *
notes (string)
+ *
a description of the item;
+ * + *
url (string)
+ *
a URL for the item’s source;
+ * + *
version (string)
+ *
must be between no longer than 100 characters
+ * + *
state (string, default='active')
+ *
+ * the current state of the item, e.g. 'active' or 'deleted', only active items show up in search results and other lists of items, + * this parameter will be ignored if you are not authorized to change the state of the item; + *
+ * + *
groups (list of dictionaries)
+ *
+ * the groups to which the item belongs, each group dictionary should have one or more of the + * following keys which identify an existing group: + * 'id' (the id of the group, string), or 'name' (the name of the group, string). + * To see which groups exist use Group listing API.
+ * + * + *
tags (list of tag dictionaries)
+ *
+ * the item’s tags. The tag is a dictionary in the format: + * name : the name for the tag, i.e. a string between 2 and 100 characters long containing only alphanumeric characters and '-', '_' and '.'. + *
+ * + * + *
resources (list of resource dictionaries)
+ *
the item’s resources, see Resource collection for the format of resource dictionaries;
+ * + * + *
extras (list of item extra dictionaries)
+ *
the item’s extras, extras are arbitrary (key: value) metadata items that can be added to items, each extra dictionary should have keys 'key' (a string), 'value' (a string);
+ * + *
owner_org (string)
+ *
+ * the id of the item’s owning organization, see supportedOrganizations property in + * Read Configuration. + * The defaultOrganization is used if the author does not specify the organization. + *
+ * + *
+ * + * + *

Parameter automatically managed:

+ *
+ * + *
author (string)
+ *
the name of the item’s author (the owner of the gcube-token);
+ * + *
author_email (string)
+ *
the email address of the item’s author (the email of the owner of gcube-token);
+ * + *
+ * + * + *

Geo-Indexing your datasets:

+ *

+ * In order to make an Item searchable by location, it must have a special extra, with its key named ‘spatial’. + * The value must be a valid GeoJSON geometry, for example: + *

+ * 
+	 * 	{
+	 * 		"type":"Polygon",
+	 * 		"coordinates":[[[2.05827, 49.8625],[2.05827, 55.7447], [-6.41736, 55.7447], [-6.41736, 49.8625], [2.05827, 49.8625]]]
+	 * 	}
+	 *
+ * + * or + * + * 
+	 * 	{
+	 * 		"type": "Point",
+	 * 		"coordinates": [-3.145,53.078]
+	 * 	}
+	 *
+ * + * + *

Profile

+ *

+ * If at least one profile has been defined within this context, then you need to specify the profile's + * type when creating the item. + * You need to insert, among the extras of the JSON object describing the item, a system:type + * property with one of the available profile, see List Profiles API. + * The validation of the submitted request will be performed against the profile whose type has been specified. + * The profile's properties need to be specified within the extras field as well. + *

+ *

+ * If no profile has been defined, then no validation will be performed. + * Thus you do not need to set any system:type property. + *

+ * + * + *

Social Post

+ *

+ * the creating user can indicate if he/she desires the creation of a social post + * to inform all the users of the VRE that he/she has created the item.
+ * To request the social post he/she must indicate social_post=true query parameter.
+ * The social_post query parameter is optional and the default value is false.
+ * Please note that even the user indicates social_post=true the social post + * is create only and only if the Catalogue-Manager enabled this feature, see socialPostEnabled property in + * Read Configuration. + *

+ * + * + * @param json containing the item to be created + * @return 201 Created HTTP Status to indicate that the item has been created. + * Some operation could continue in background such as the social post creation. + */ @POST @Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)