GCat Service

The gCube Science Catalogue Service is a RESTful web service based on the principles defined in gCube Catalogue

Request

URL

The URL used to interact with the Science Catalogue Service is composed of two parts:

• Base Service URL (e.g. https:/catalogue.d4science.org/science-catalogue)
• Specific API (e.g. /organizations)

D4Science infrastructure uses cloud facilities allowing to replicate a service to achieve failover and load balancing.

Science Catalogue Service instances can be deployed and undeployed dynamically. For such a reason the Base Service URL MUST NOT be hard-cabled in the code because it can change over time.

To dynamically discover the Base Service URL please use the information system.

You need to discover gCore Resource having:

• class : DataCatalogue
• name : science-catalogue

HTTP Methods

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

The URL pattern is

Operation	HTTP Method	URL
List	GET	/{COLLECTION}
Create	POST	/{COLLECTION}
Read	GET	/{COLLECTION}/{INSTANCE_ID}
Update	PUT	/{COLLECTION}/{INSTANCE_ID}
Patch	PATCH	/{COLLECTION}/{INSTANCE_ID}
Delete	DELETE	/{COLLECTION}/{INSTANCE_ID}
Purge	PURGE	/{COLLECTION}/{INSTANCE_ID}
Purge	DELETE	/{COLLECTION}/{INSTANCE_ID}?purge=true

Where:

• {COLLECTION} is the plural name of the entity type
• {INSTANCE_ID} is an identification which enables to univocally identify the instance in the collection

You can find more information about this at https://restfulapi.net/http-methods/

PURGE Method is not a standard HTTP Method but is a widely used in service which requires this action (e.g. Varnish, Squid)

The Science Catalogue 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

HTTP Headers

gCube Authorization Token

Any request performed to Science Catalogue MUST contains the gCube Authorization Token.

This is done using the HTTP Header gcube-token

gcube-token: YOUR-TOKEN

Retrieve your gCube Authorization Token

the gCube Authorization Token is an UUID bound to yourself and a given Infrastructure context. To retrieve it, you just need to go to a VRE for which you are interested and use the Authorisation Options portlet (see below)

Click on Show button and select the token.

Collections

• Group
• Item
• Resource
• License
• Organization
• User
• Profile
• Namespace

Group Collection

Operation	HTTP Method	URL
List	GET	/groups
Create	POST	/groups
Read	GET	/groups/{NAME}
Update	PUT	/groups/{NAME}
Patch	PATCH	/groups/{NAME}
Delete	DELETE	/groups/{NAME}
Purge	PURGE	/groups/{NAME}
Purge	DELETE	/groups/{NAME}?purge=true

Item Collection

Operation	HTTP Method	URL
List	GET	/items
Create	POST	/items
Read	GET	/items/{NAME}
Update	PUT	/items/{NAME}
Delete	DELETE	/items/{NAME}
Purge	PURGE	/items/{NAME}
Purge	DELETE	/items/{NAME}?purge=true

Resource Collection

Operation	HTTP Method	URL
List	GET	/items/{NAME}/resources
Create	POST	/items/{NAME}/resources
Read	GET	/items/{NAME}/resources/{ID}
Update	PUT	/items/{NAME}/resources/{ID}
Delete	DELETE	/items/{NAME}/resources/{ID}

License Collection

Operation	HTTP Method	URL
List	GET	/licenses

Organization Collection

Operation	HTTP Method	URL
List	GET	/organizations
Create	POST	/organizations
Read	GET	/organizations/{NAME}
Update	PUT	/organizations/{NAME}
Patch	PATCH	/organizations/{NAME}
Delete	DELETE	/organizations/{NAME}
Purge	PURGE	/organizations/{NAME}
Purge	DELETE	/organizations/{NAME}?purge=true

User Collection

Operation	HTTP Method	URL
List	GET	/users
Create	POST	/users
Read	GET	/users/{NAME}
Update	PUT	/users/{NAME}
Delete	DELETE	/users/{NAME}

Profile Collection

Operation	HTTP Method	URL
List	GET	/profiles
Read	GET	/profiles/{NAME}

A profile is defined using XML. It is possible to get the original XML definition using 'Accept' HTTP Header.

Accept : application/xml

instead of

Accept : application/json

Namespace Collection

Operation	HTTP Method	URL
List	GET	/namespaces