Improving documentation
This commit is contained in:
parent
708f9e38e9
commit
c60d99381d
|
|
@ -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) <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
|
||||
|
||||
*******
|
||||
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*.
|
||||
|
|
@ -61,9 +58,8 @@ Please use this checklist before reporting an error:
|
|||
* 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.
|
||||
|
||||
|
|
@ -116,7 +112,7 @@ gCat is a pure RESTful service. It uses standard HTTP Methods to perform a listi
|
|||
|
||||
|
||||
About URL
|
||||
*********
|
||||
^^^^^^^^^
|
||||
|
||||
The presented URL uses the following convention:
|
||||
|
||||
|
|
@ -125,7 +121,8 @@ The presented URL uses the following convention:
|
|||
|
||||
|
||||
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"
|
||||
|
|
@ -137,7 +134,7 @@ About Safety and Idempotency properties
|
|||
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
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
|
||||
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
|
||||
|
|
|
|||
Loading…
Reference in New Issue