gCubeSystem
/
gcat
16
0
Fork 0
Code Issues Pull Requests Releases 13 Wiki Activity
gcat/docs/index.rst

14 KiB
Raw Blame History

Welcome to gCat documentation!

gCat is a RESTful application which exposes operations ...

See the available REST-API on its API docs.

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. JSON Web Token (JWT) Access token are used for both authentication and authorization.

Obtain your Bearer token here: https://dev.d4science.org/how-to-access-resources

Service

The methods of the Web Service can be called by writing your own REST client application or by using already existing REST client plugins.

HTTP Statuses

Any successful operation returns 200 OK status code except for create operation which return 201 Created or for the operations which do not provide any content and returns 204 No Content.

The most common error status a client can obtain are:

A complete list of HTTP Status can be found here: 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 so please retry the request after a certain amount of time;
  • indicate how to replicate the error;
  • indicate the time when the error occurred (this simplify the identification of the issue).

HTTP Methods

To be RESTful compliant, gCat uses standard HTTP Methods to perform a listing of collections and CRUD (Create Read Update Delete) operations on instances.

Operation

 HTTP Method URL Success HTTP Status

Safe

 Idempotent
Supported HTTP Methods OPTIONS /{COLLECTION} 204 No Content 1

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 2

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

N3
Purge DELETE /{COLLECTION}/{INSTANCE_ID}?purge=true 204 No Content

N

N4
PURGE /{COLLECTION}/{INSTANCE_ID} 204 No Content

N

N5

About URL

The presented URL uses the following convention:

  • {COLLECTION} is the plural name of the entity type;
  • {INSTANCE_ID} is an identification which enables to univocally identify 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 provide only the differences and not the whole new representation);
  • PURGE method is not a standard but is a widely used in service which requires this action (e.g. Varnish, Squid). gCat provide 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 the indication of the interested content type.

For any operation returning a result, the client must specify the Accept HTTP Header.

Accept: application/json

For any operation sending content to the service, it is necessary to specify the Content-Type HTTP Header.

Content-Type: application/json

Actually, the service accepts and returns only JSON objects.

Except for a Profile Collection which must be manipulated in in XML.

Collections

The following collections are available to any users. Non-safe methods can only be invoked by Catalogue-Editor or above.

The following collections are available only for Catalogue-Admins or above:

An overwiew of the available collections is available at ../api-docs/index.html;

Roles

Any user has one or more role in the catalogue. Roles can only be assigned by the VRE Manager.

The catalogue uses the following hierarchic roles:

Catalogue-Member:

a user with such a role is mainly capable of listing and reading items;

Catalogue-Editor:

a user with such a role is capable of managing the items he/she creates and capable of using other safe APIs;

Catalogue-Admin:

a user with such a role is capable of administrating many aspects of the catalogue;

Catalogue-Manager:

a user with such a role is capable of using all the APIs exposed by the service except moderation item APIs (i.e. approve, reject).

Another role that is not in the role hierarchy:

Catalogue-Moderator:

a user with such a role is capable of invoking the item moderation APIs.

Tip

Please note that not all catalogues are moderated.

Moderated Catalogues ==================

Any catalogues can be declared as moderated. In such a case any submitted items must be approved by a Catalogue-Moderator.

In a moderated catalogue, an item can be in the following states:

pending:

the item published by any allowed users and still not Catalogue-Moderator;

approved:

the item published by any allowed users and rejected by a Catalogue-Moderator;

rejected:

the item published by any allowed users and approved by a Catalogue-Moderator.

In the following are presented the moderation operations an allowed user can perform to an item. To present the moderation operation the following convenction is used:

initial_state ---operation (User/Role perfoming the operation)---> final_state

initial_state can be none which means that the item does not exists.

The following are the allowed moderation operation on a item in a and the

none ---create (Author)---> pending

pending ---reject (Catalogue-Moderator)---> rejected

pending ---approve (Catalogue-Moderator)---> approved

rejected ---update (Author)---> rejected

approved ---update (Author)---> pending

In a moderated catalogue both the Catalogue-Moderators and the item author can send messages to discuss about the approval process of the item. The message are related to a specific item. A message sent by an Author is received by any Catalogue-Moderators. A message sent by a Catalogue-Moderator is received by the author as weel as the other Catalogue-Moderators (if any).

Messages can be sent both together with an action which change the status of the item or as explicit action which does not change the status of the item:

pending ---message (Author OR Catalogue-Moderator)---> pending

rejected ---message (Author OR Catalogue-Moderator)---> rejected

approved ---message (Author OR Catalogue-Moderator)---> approved

Java Client

We provide the following Java Client out-of-the-box.

Tip

If you're coding in Java it is recommended that you use this Java Client.

Maven Coordinates

<groupId>org.gcube.data-catalogue</groupId>
<artifactId>gcat-client</artifactId>
<version>[2.2.0, 3.0.0-SNAPSHOT)</version>

Methods Result

The service exposes its methods using a standard naming approach. Moreover, they accept (in case of http POST/PUT methods) JSON objects.

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

  • Example 1
import org.gcube.gcat.client.Item;

// count item number
Item item = new Item();
int count = item.count();
...