Improving documentation
This commit is contained in:
parent
708f9e38e9
commit
c60d99381d
|
|
@ -1,20 +1,19 @@
|
||||||
#############################
|
=============================
|
||||||
Welcome to gCat documentation
|
Welcome to gCat documentation
|
||||||
#############################
|
=============================
|
||||||
|
|
||||||
gCat is a RESTful application which exposes operations ...
|
gCat is a RESTful application which exposes operations ...
|
||||||
|
|
||||||
See the available REST-API on `its API docs <../api-docs/index.html>`_.
|
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
|
In the production environment, its current value is https://api.d4science.org/gcat
|
||||||
|
|
||||||
*************
|
|
||||||
Authorization
|
Authorization
|
||||||
*************
|
=============
|
||||||
|
|
||||||
D4Science adopts state-of-the-art industry standards for authentication and 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.
|
Specifically, the implementation fully adopts `OIDC (OpenID Connect) <https://openid.net/connect>`_ for authentication and UMA 2 (User-Managed Authorization) for authorization flows.
|
||||||
|
|
@ -22,16 +21,14 @@ Specifically, the implementation fully adopts `OIDC (OpenID Connect) <https://op
|
||||||
|
|
||||||
Obtain your Bearer token here: https://dev.d4science.org/how-to-access-resources
|
Obtain your Bearer token here: https://dev.d4science.org/how-to-access-resources
|
||||||
|
|
||||||
*******
|
|
||||||
Service
|
Service
|
||||||
*******
|
=======
|
||||||
|
|
||||||
|
|
||||||
You can call the methods of the Web Service by writing your own REST client application or using existing REST client plugins.
|
You can call the methods of the Web Service by writing your own REST client application or using existing REST client plugins.
|
||||||
|
|
||||||
=============
|
|
||||||
HTTP Statuses
|
HTTP Statuses
|
||||||
=============
|
-------------
|
||||||
|
|
||||||
Any successful operation returns *200 OK* HTTP status code.
|
Any successful operation returns *200 OK* HTTP status code.
|
||||||
The create operation returns *201 Created*.
|
The create operation returns *201 Created*.
|
||||||
|
|
@ -61,9 +58,8 @@ Please use this checklist before reporting an error:
|
||||||
* indicate how to replicate the error;
|
* indicate how to replicate the error;
|
||||||
* indicate the time when the error occurred (this simplifies identifying the issue).
|
* indicate the time when the error occurred (this simplifies identifying the issue).
|
||||||
|
|
||||||
============
|
|
||||||
HTTP Methods
|
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.
|
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.
|
||||||
|
|
||||||
|
|
@ -116,7 +112,7 @@ gCat is a pure RESTful service. It uses standard HTTP Methods to perform a listi
|
||||||
|
|
||||||
|
|
||||||
About URL
|
About URL
|
||||||
*********
|
^^^^^^^^^
|
||||||
|
|
||||||
The presented URL uses the following convention:
|
The presented URL uses the following convention:
|
||||||
|
|
||||||
|
|
@ -125,7 +121,8 @@ The presented URL uses the following convention:
|
||||||
|
|
||||||
|
|
||||||
About Safety and Idempotency properties
|
About Safety and Idempotency properties
|
||||||
***************************************
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
|
||||||
* A method is *Safe* if it does not produce any side effects.
|
* 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"
|
"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"
|
||||||
|
|
@ -137,7 +134,7 @@ About Safety and Idempotency properties
|
||||||
You can find more information about HTTP Methods at `<https://restfulapi.net/http-methods/>`_
|
You can find more information about HTTP Methods at `<https://restfulapi.net/http-methods/>`_
|
||||||
|
|
||||||
Uncommon 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);
|
* 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
|
* 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``.
|
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
|
Content-Type
|
||||||
============
|
------------
|
||||||
|
|
||||||
Any request must contain an indication of the interesting 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.
|
`Profile Collection <../api-docs/resource\_Profile.html>`_ instead can be manipulated in XML only.
|
||||||
|
|
||||||
===========
|
|
||||||
Collections
|
Collections
|
||||||
===========
|
-----------
|
||||||
|
|
||||||
The following collections are available to any user.
|
The following collections are available to any user.
|
||||||
Catalogue-Editor or above can invoke Non-safe methods only.
|
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>`_;
|
An overview of the available collections is available at `<../api-docs/index.html>`_;
|
||||||
|
|
||||||
|
|
||||||
=====
|
|
||||||
Roles
|
Roles
|
||||||
=====
|
-----
|
||||||
|
|
||||||
Any user has one or more roles in the catalogue.
|
Any user has one or more roles in the catalogue.
|
||||||
The VRE Manager can only assign roles.
|
The VRE Manager can only assign roles.
|
||||||
|
|
@ -225,9 +219,9 @@ Catalogue-Moderator:
|
||||||
.. TIP::
|
.. TIP::
|
||||||
Please note that not all catalogues are moderated.
|
Please note that not all catalogues are moderated.
|
||||||
|
|
||||||
********************
|
|
||||||
Moderated Catalogues
|
Moderated Catalogues
|
||||||
********************
|
====================
|
||||||
|
|
||||||
|
|
||||||
Any catalogues can be declared as moderated.
|
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.
|
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
|
Java Client
|
||||||
***********
|
===========
|
||||||
|
|
||||||
We provide the following Java Client out-of-the-box.
|
We provide the following Java Client out-of-the-box.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -231,7 +231,150 @@ public class Item extends REST<CKANPackage> 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):
|
||||||
|
*
|
||||||
|
*
|
||||||
|
* <dl>
|
||||||
|
* <dt>name* (string)</dt>
|
||||||
|
* <dd>
|
||||||
|
* the name of the new item, must be between 2 and 100 characters long
|
||||||
|
* and contain only lowercase alphanumeric characters, '-' and '_';
|
||||||
|
* </dd>
|
||||||
|
*
|
||||||
|
*
|
||||||
|
* <dt style="margin-top: 5px;">title (string)</dt>
|
||||||
|
* <dd>
|
||||||
|
* If not specified it assumes the same value of <em>name</em> attribute.
|
||||||
|
* The title of the item;
|
||||||
|
* </dd>
|
||||||
|
*
|
||||||
|
* <dt style="margin-top: 5px;">maintainer (string)</dt>
|
||||||
|
* <dd>the name of the item’s maintainer;</dd>
|
||||||
|
*
|
||||||
|
* <dt style="margin-top: 5px;">maintainer_email (string)</dt>
|
||||||
|
* <dd>the email address of the item’s maintainer;</dd>
|
||||||
|
*
|
||||||
|
* <dt style="margin-top: 5px;">license_id* (string)</dt>
|
||||||
|
* <dd>the id of the item’s license, use <a href="../resource_License.html">License listing</a> API to get available values;</dd>
|
||||||
|
*
|
||||||
|
* <dt style="margin-top: 5px;">notes (string)</dt>
|
||||||
|
* <dd>a description of the item;</dd>
|
||||||
|
*
|
||||||
|
* <dt style="margin-top: 5px;">url (string)</dt>
|
||||||
|
* <dd>a URL for the item’s source;</dd>
|
||||||
|
*
|
||||||
|
* <dt style="margin-top: 5px;">version (string)</dt>
|
||||||
|
* <dd>must be between no longer than 100 characters</dd>
|
||||||
|
*
|
||||||
|
* <dt style="margin-top: 5px;">state (string, default='active')</dt>
|
||||||
|
* <dd>
|
||||||
|
* 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;
|
||||||
|
* </dd>
|
||||||
|
*
|
||||||
|
* <dt style="margin-top: 5px;">groups (list of dictionaries)</dt>
|
||||||
|
* <dd>
|
||||||
|
* 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 <a href="../resource_Group.html#resource_Group_list_limit_offset_countOnly_GET">Group listing</a> API.</dd>
|
||||||
|
* </dd>
|
||||||
|
*
|
||||||
|
* <dt style="margin-top: 5px;">tags (list of tag dictionaries)</dt>
|
||||||
|
* <dd>
|
||||||
|
* 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 '.'.
|
||||||
|
* </dd>
|
||||||
|
*
|
||||||
|
*
|
||||||
|
* <dt style="margin-top: 5px;">resources (list of resource dictionaries)</dt>
|
||||||
|
* <dd>the item’s resources, see <a href="../resource_Resource.html">Resource collection</a> for the format of resource dictionaries;</dd>
|
||||||
|
*
|
||||||
|
*
|
||||||
|
* <dt style="margin-top: 5px;">extras (list of item extra dictionaries)</dt>
|
||||||
|
* <dd>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);</dd>
|
||||||
|
*
|
||||||
|
* <dt style="margin-top: 5px;">owner_org (string)</dt>
|
||||||
|
* <dd>
|
||||||
|
* the id of the item’s owning organization, see <code>supportedOrganizations</code> property in
|
||||||
|
* <a href="../resource_Configuration.html#resource_Configuration_read_context_GET">Read Configuration</a>.
|
||||||
|
* The <code>defaultOrganization</code> is used if the author does not specify the organization.
|
||||||
|
* </dd>
|
||||||
|
*
|
||||||
|
* </dl>
|
||||||
|
*
|
||||||
|
*
|
||||||
|
* <h3>Parameter automatically managed:</h3>
|
||||||
|
* <dl>
|
||||||
|
*
|
||||||
|
* <dt style="margin-top: 5px;">author (string)</dt>
|
||||||
|
* <dd>the name of the item’s author (the owner of the gcube-token);</dd>
|
||||||
|
*
|
||||||
|
* <dt style="margin-top: 5px;">author_email (string)</dt>
|
||||||
|
* <dd>the email address of the item’s author (the email of the owner of gcube-token);</dd>
|
||||||
|
*
|
||||||
|
* </dl>
|
||||||
|
*
|
||||||
|
*
|
||||||
|
* <h3>Geo-Indexing your datasets:</h3>
|
||||||
|
* <p>
|
||||||
|
* 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:
|
||||||
|
* </p>
|
||||||
|
* <pre>
|
||||||
|
* {
|
||||||
|
* "type":"Polygon",
|
||||||
|
* "coordinates":[[[2.05827, 49.8625],[2.05827, 55.7447], [-6.41736, 55.7447], [-6.41736, 49.8625], [2.05827, 49.8625]]]
|
||||||
|
* }
|
||||||
|
* </pre>
|
||||||
|
*
|
||||||
|
* or
|
||||||
|
*
|
||||||
|
* <pre>
|
||||||
|
* {
|
||||||
|
* "type": "Point",
|
||||||
|
* "coordinates": [-3.145,53.078]
|
||||||
|
* }
|
||||||
|
* </pre>
|
||||||
|
*
|
||||||
|
*
|
||||||
|
* <h3>Profile</h3>
|
||||||
|
* <p>
|
||||||
|
* 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 <code>system:type</code>
|
||||||
|
* property with one of the available profile, see <a href="..//resource_Profile.html#resource_Profile_listOrCount_countOnly_GET">List Profiles</a> 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.
|
||||||
|
* </p>
|
||||||
|
* <p>
|
||||||
|
* If no profile has been defined, then no validation will be performed.
|
||||||
|
* Thus you do not need to set any <code>system:type</code> property.
|
||||||
|
* </p>
|
||||||
|
*
|
||||||
|
*
|
||||||
|
* <h3>Social Post</h3>
|
||||||
|
* <p>
|
||||||
|
* 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.</br>
|
||||||
|
* To request the social post he/she must indicate <code>social_post=true</code> query parameter.<br/>
|
||||||
|
* The <code>social_post</code> query parameter is optional and the default value is <code>false</code>.<br/>
|
||||||
|
* Please note that even the user indicates <code>social_post=true</code> the social post
|
||||||
|
* is create only and only if the Catalogue-Manager enabled this feature, see <code>socialPostEnabled</code> property in
|
||||||
|
* <a href="../resource_Configuration.html#resource_Configuration_read_context_GET">Read Configuration</a>.
|
||||||
|
* </p>
|
||||||
|
*
|
||||||
|
*
|
||||||
|
* @param json containing the item to be created
|
||||||
|
* @return <code>201 Created</code> HTTP Status to indicate that the item has been created.
|
||||||
|
* Some operation could continue in background such as the social post creation.
|
||||||
|
*/
|
||||||
@POST
|
@POST
|
||||||
@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
|
@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
|
||||||
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
|
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue