Revision as of 11:43, 23 May 2017

** THIS PAGE IS UNDER CONSTRUCTION **

Catalogue Web Service

Starting from gCube 4.5 a new RESTFul Web Service has been created to let external services/users interact with the D4Science's catalogues. It exploits the underneath CKAN^[1] APIs, but at the same time allows to perform operations on the catalogue using the security gCube token.

You are suggested to read the main catalogue wiki page before continue.

Retrieve your gCube Security Token

A security token is a UUID bind to yourself and a given Infrastructure context. To retrieve it, you just need to go to a VRE for which you are interested in retrieving it, and use the Authorisation Options portlet (see below)

Click on Show button and select the token. We will use it later on.

Retrieve web service endpoint

The service endpoint url depends on the context you are interesting in. You could either access to the Infrastructure Monitor of the Infrastructure and looking for a GCore EndPoint having as name Catalogue-WS and Service Class Data-Catalogue, or perform the same look up operation programmatically with the ICClient library.

For the development environment, it is available at:

http://catalogue-ws-d-d4s.d4science.org/catalogue-ws/rest

Supported operations Overview (gCube 4.5)

The APIs allow to interact with the catalogue and perform the following operations on it. Please note that they return a JSON object. Be sure to set the following headers in your http requests

Content-type : application/json
Accept: application/json

Licenses

Subpath

api/licenses/

Retrieve the list of licenses

Path

SERVICE_ENDPOINT/api/licenses/list?gcube-token=....

HTTP Method type: GET

Organizations

Subpath

api/organizations/

Show organization

Path

SERVICE_ENDPOINT/api/organizations/show?id=organization_name&gcube-token=....

HTTP Method type: GET

Return the details of a organization. Parameters:

   id (boolean) – the id or name of the organization
   include_datasets (boolean) – include a truncated list of the org’s datasets (optional, default: False)
   include_dataset_count (boolean) – include the full package_count (optional, default: True)
   include_extras – include the organization’s extra fields (optional, default: True)
   include_users – include the organization’s users (optional, default: True)
   include_groups – include the organization’s sub groups (optional, default: True)
   include_tags – include the organization’s tags (optional, default: True)
   include_followers – include the organization’s number of followers (optional, default: True)

Show organizations list

Path

SERVICE_ENDPOINT/api/organizations/list?gcube-token=....

HTTP Method type: GET

Return a list of the names of the site’s organizations. Parameters:

   order_by (string) – the field to sort the list by, must be 'name' or 'packages' (optional, default: 'name') Deprecated use sort.
   sort (string) – sorting of the search results. Optional. Default: “name asc” string of field name and sort-order. The allowed fields are ‘name’, ‘package_count’ and ‘title’
   limit (int) – if given, the list of organizations will be broken into pages of at most limit organizations per page and only one page will be returned at a time (optional)
   offset (int) – when limit is given, the offset to start returning organizations from
   organizations (list of strings) – a list of names of the groups to return, if given only groups whose names are in this list will be returned (optional)
   all_fields (boolean) – return group dictionaries instead of just names. Only core fields are returned - get some more using the include_* options. Returning a list of packages is too expensive, so the packages property for each group is deprecated, but there is a count of the packages in the package_count property. (optional, default: False)
   include_dataset_count (boolean) – if all_fields, include the full package_count (optional, default: True)
   include_extras (boolean) – if all_fields, include the organization extra fields (optional, default: False)
   include_tags (boolean) – if all_fields, include the organization tags (optional, default: False)
   include_groups – if all_fields, include the organizations the organizations are in (optional, default: False)
   include_users (boolean) – if all_fields, include the organization users (optional, default: False).

Create organization

Path

SERVICE_ENDPOINT/api/organizations/create?name=organization_name&gcube-token=....

HTTP Method type: POST Please note that only SysAdmin can perform this operation

Create a new organization.

You must be authorized to create organizations.

Plugins may change the parameters of this function depending on the value of the type parameter, see the IGroupForm plugin interface. Parameters:

   name (string) – the name of the organization, a string between 2 and 100 characters long, containing only lowercase alphanumeric characters, - and _
   id (string) – the id of the organization (optional)
   title (string) – the title of the organization (optional)
   description (string) – the description of the organization (optional)
   image_url (string) – the URL to an image to be displayed on the organization’s page (optional)
   state (string) – the current state of the organization, e.g. 'active' or 'deleted', only active organizations show up in search results and other lists of organizations, this parameter will be ignored if you are not authorized to change the state of the organization (optional, default: 'active')
   approval_status (string) – (optional)
   extras (list of dataset extra dictionaries) – the organization’s extras (optional), extras are arbitrary (key: value) metadata items that can be added to organizations, each extra dictionary should have keys 'key' (a string), 'value' (a string), and optionally 'deleted'
   packages (list of dictionaries) – the datasets (packages) that belong to the organization, a list of dictionaries each with keys 'name' (string, the id or name of the dataset) and optionally 'title' (string, the title of the dataset)
   users (list of dictionaries) – the users that belong to the organization, a list of dictionaries each with key 'name' (string, the id or name of the user) and optionally 'capacity' (string, the capacity in which the user is a member of the organization)

Returns:

the newly created organization (unless ‘return_id_only’ is set to True in the context, in which case just the organization id will be returned)

Update organization

Path

SERVICE_ENDPOINT/api/organizations/update?name=organization_name&gcube-token=....

HTTP Method type: POST Please note that only SysAdmin can perform this operation

Patch organization

Path

SERVICE_ENDPOINT/api/organizations/show?name=organization_name&gcube-token=....

Please note that only SysAdmin can perform this operation

Delete organization

Path

SERVICE_ENDPOINT/api/organizations/show?name=organization_name&gcube-token=....

Please note that only SysAdmin can perform this operation

Purge organization

Path

SERVICE_ENDPOINT/api/organizations/show?name=organization_name&gcube-token=....

Please note that only SysAdmin can perform this operation

Groups

Resources

Items

Items Profiles

1. ↑ An overview about this technology and the APIs it offers can be found here http://docs.ckan.org/en/latest/api/