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

22 KiB
Raw Blame History

Welcome to gCube Catalogue Service (aka gCat) documentation

gCat is a RESTful application which exposes operations ...

See the available REST-API on its API docs.

The maven coordinates are:

<groupId>org.gcube.data-catalogue</groupId>
<artifactId>gcat</artifactId>

The service can be discovered in the gCore IS as gCore Endpoint with the following parameter:

<ServiceClass>org.gcube.data-catalogue</ServiceClass>
<ServiceName>gcat</ServiceName>

The service can be discovered in the Facet Based IS as EService with the following json query:

{
    "@class": "EService",
    "consistsOf": [
        {
            "@class": "IsIdentifiedBy",
            "target": {
                "@class": "SoftwareFacet",
                "group": "org.gcube.data-catalogue",
                "name": "gcat"
            }
        }
    ]
}

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

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:

You can find a complete list of HTTP Status at https://httpstatuses.com/

If you get a 500 Internal Server Error, please report it in the gCube ticketing system.

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

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.

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 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" 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 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, Squid). 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.

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

The service accepts and returns only JSON objects.

Profile Collection 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.

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. Only the VRE Manager can assign roles to VRE users.

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 can use all the APIs exposed by the service except item moderation APIs (e.g. 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. This means that, a Catalogue-Moderator must approve any submitted items to make them available to the other users of the catalogue.

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

pending:

The item published by any allowed author (a Catalogue-Editor or above) but not available to the other users of the catalogue. A Catalogue-Moderator has to approve or reject it;

approved:

A Catalogue-Moderator has approved the item published by any allowed users;

rejected:

A Catalogue-Moderator has rejected the item published by any allowed users.

The following are the moderation operations that an allowed user can perform on an item. To present the moderation operations, we use the following convention:

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

initial_state can be none, meaning the item does not exist.

The following are the allowed moderation operation on an item

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

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

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

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

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

Please check the table below whcih summarise the item collection opration and the allowed users/roles.

In a moderated catalogue, both the Catalogue-Moderators and the item author can send messages to discuss the approval process of the item. The messages are related to a specific item. Any Catalogue-Moderators receive a message sent by an Author. The author receives a message sent by a Catalogue-Moderator as well as the other Catalogue-Moderators (if any).

Messages can be sent both with an action which changes 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

The following table summarize the allowed/forbidden operations depending on: the role of the user and the state of the item.

Operation Item State Roles
Catalogue Moderator Catalogue Admin/Manager Catalogue Editor Catalogue Member
List Yes all states Yes all states Yes only approved - All states if Author Yes only approved
Count Yes all states Yes all states Yes only approved - All states if Author Yes only approved
Create 403 Forbidden Yes -> Pending Yes -> Pending 403 Forbidden
Read Yes all states Yes all states Yes only approved - All states if Author Yes only approved
Update Pending Yes -> Pending Yes if Author -> Pending Yes if Author -> Pending 403 Forbidden
Rejected Yes -> Pending Yes if Author -> Pending Yes if Author -> Pending 403 Forbidden
Approved 403 Forbidden Yes -> Approved Yes if Author -> Pending 403 Forbidden
Delete/Purge Pending Yes Yes Yes if Author 403 Forbidden
Rejected Yes Yes Yes if Author 403 Forbidden
Approved 403 Forbidden Yes Yes if Author 403 Forbidden
Approve a pending item Yes 403 Forbidden 403 Forbidden 403 Forbidden
Reject a pending item Yes 403 Forbidden 403 Forbidden 403 Forbidden
Message about an item Yes Yes if Author Yes if Author 403 Forbidden

The Moderation process has associated notification to authors and Catalogue-Moderators. Please note that the user who has acted is not self-notified, e.g. approve operation made by a Catalogue-Moderator notifies the item author and the other Catalogue-Moderators of the VRE.

The following table summarises the addressee of the notification for any action.

Operation Notified user/role
Catalogue-Moderators Author
Create Yes No
Update Yes Yes
Approve Yes + Social Post if enabled for the VRE
Reject Yes Yes
Message Yes Yes

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 the 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();
...