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 it also provides the Purge action via DELETE with the additional get parameter <pres>purge=true</pre>.

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