GCat Service

From Gcube Wiki
Revision as of 18:30, 3 December 2018 by Luca.frosini (Talk | contribs) (→‎Profile Collection)

Jump to: navigation, search

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 you can use the Registry RESTful Service

You need to discover gCore Resource having:

  • class : DataCatalogue
  • name : science-catalogue

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

The gcube-token HTTP header acts as the standard Authorization HTTP header. Plese note that Authorization HTTP header cannot be used in place of gcube-token HTTP header.

Retrieve your gCube Authorization Token

the gCube Authorization Token is a 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)

Authorisation option.png

Click on Show button and select the token.

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 which can be also requested in XML.

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/

You can report a 500 Internal Server Error the ticketing system. 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 Science Catalogue 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
(Supported HTTP Methods in Allow HTTP Header) 		Y Y
List GET /{COLLECTION} 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
(Supported HTTP Methods in Allow HTTP Header) 		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 N ‡
Purge PURGE /{COLLECTION}/{INSTANCE_ID} 204 No Content N N ‡
Purge DELETE /{COLLECTION}/{INSTANCE_ID}?purge=true 204 No Content N N ‡


About URL:

  • {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.

‡ DELETE has been defined as idempotent. Allamaraju[1] argues that DELETE idempotency should be accomplished client-side. The server should inform the client if a delete succeeded because the resource was really deleted or it was not found i.e., 404 Not Found error is suggested instead of 204 No Content. The latter situation should be treated as idempotent by the client. For this reason, Science Catalogue does not provide server-side idempotency for DELETE and PURGE operations.

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). 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

Collections

Collection available to any users. Non-safe methods can only be invoked by #Users.2C_Roles_and_Groups Catalogue Editor

Collection availables only for #Users.2C_Roles_and_Groups Catalogue_Admin


For each collection HEAD and OPTIONS operations are not shown in tables even there are always available.

To keep this documentation simple, for each collection is presented only the relevant attributes of an instance. This allows getting the picture of the content of a request or the content of a response.

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


  • name* (string): the name of the new item, must be between 2 and 100 characters long and contain only lowercase alphanumeric characters, '-' and '_';
  • title (string, defaut="same as name"): the title of the item;
  • private* (bool): If True creates a private item;
  • maintainer (string): the name of the item’s maintainer;
  • maintainer_email (string): the email address of the item’s maintainer;
  • license_id (license id string): the id of the item’s license, see license_list() for available values;
  • notes (string): a description of the item;
  • url (string): a URL for the item’s source;
  • version (string, no longer than 100 characters): ...;
  • state (string, default='active'): the current state of the item, e.g. 'active' or 'deleted', only active items show up in search results and other lists of items, this parameter will be ignored if you are not authorized to change the state of the item;
  • groups (list of dictionaries): the groups to which the item belongs, each group dictionary should have one or more of the following keys which identify an existing group: 'id' (the id of the group, string), or 'name' (the name of the group, string). To see which groups exist use list method in #Group_Collection Group Collection
  • tags (list of tag dictionaries): the item’s tags. The tag is a dictionary in the format:
    • name : the name for the tag, a string between 2 and 100 characters long containing only alphanumeric characters and '-, '_' and '.'.
  • resources (list of resource dictionaries): the item’s resources, see #Resource_Collection Resource Collection for the format of resource dictionaries;
  • extras (list of item extra dictionaries): the item’s extras, extras are arbitrary (key: value) metadata items that can be added to items, each extra dictionary should have keys 'key' (a string), 'value' (a string).

Parameter automatically managed:

  • author (string): the name of the item’s author (the owner of the gcube-token);
  • author_email (string): the email address of the item’s author (the email of the owner of gcube-token);
  • owner_org (string): the id of the item’s owning organization, see organization_list() or organization_list_for_user() for available values (the VRE corrsponding to the gcube-token)


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}

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

An example of Profiles listing is : 

[
    "EOSCService",
    "SoBigData.eu: Dataset Metadata",
    "SoBigData.eu: Application Metadata",
    "SoBigData.eu: Method Metadata"
]

An example of Profile is : 

<metadataformat type="EOSCService">
    <metadatafield categoryref="EOSC_BasicServiceInformation">
        <fieldName>ServiceTagline</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>Catchline or slogan of service for marketing/advertising  purposes.                </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_BasicServiceInformation">
        <fieldName>ServiceFullName</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>Extended name of service as assigned by the service provider.                </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_BasicServiceInformation">
        <fieldName>TargetCustomersUsers</fieldName>
        <mandatory>true</mandatory>
        <dataType>String</dataType>
        <defaultValue>Researcher</defaultValue>
        <note>Type of users or end-users allowed to commission/benefit from the service. E.g. Academic Community, Research Community, Community Manager, Service Provider, Researcher, Funders, Policy Makers, etc.                </note>
        <vocabulary/>
        <validator/>
        <tagging create="true" separator=".">onFieldName_onValue</tagging>
        <grouping create="true">onFieldName_onValue</grouping>
    </metadatafield>
    <metadatafield categoryref="EOSC_BasicServiceInformation">
        <fieldName>CustomerUserValue</fieldName>
        <mandatory>true</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>The benefit to a customer and their users delivered by the service. Benefits are usually related to alleviating pains (e.g., eliminate undesired outcomes, obstacles or risks) or producing gains (e.g. increased performance, social gains, positive emotions or cost saving).                </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_BasicServiceInformation">
        <fieldName>UsageAppreciation</fieldName>
        <mandatory>true</mandatory>
        <dataType>Text</dataType>
        <defaultValue/>
        <note>List of customers, communities, etc using the service.                </note>
        <vocabulary/>
        <validator/>
        <tagging create="true" separator=".">onFieldName_onValue</tagging>
        <grouping create="true">onFieldName_onValue</grouping>
    </metadatafield>
    <metadatafield categoryref="EOSC_BasicServiceInformation">
        <fieldName>ServiceProvider</fieldName>
        <mandatory>true</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>Organisation that manages and delivers the service and with whom the customer signs the SLA. E.g. GEANT, PRACE, EGI, EUDAT, OpenAIRE, etc.                </note>
        <vocabulary/>
        <validator/>
        <tagging create="true" separator=".">onValue</tagging>
        <grouping create="true">onFieldName_onValue</grouping>
    </metadatafield>
    <metadatafield categoryref="EOSC_BasicServiceInformation">
        <fieldName>Funding</fieldName>
        <mandatory>true</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>Sources of funding for the development and operation of the service.                </note>
        <vocabulary/>
        <validator/>
        <tagging create="true" separator=".">onFieldName_onValue</tagging>
        <grouping create="true">onFieldName_onValue</grouping>
    </metadatafield>
    <metadatafield categoryref="EOSC_BasicServiceInformation">
        <fieldName>ServiceWebpage</fieldName>
        <mandatory>true</mandatory>
        <dataType>String</dataType>
        <defaultValue>http://...</defaultValue>
        <note>Link to a webpage providing information about the service. This webpage is usually hosted and maintained by the service provider. It contains fresh and additional information, such as what APIs are supported or links to the documentation.                </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceClassification">
        <fieldName>ServiceVersion</fieldName>
        <mandatory>true</mandatory>
        <dataType>String</dataType>
        <defaultValue>1.0</defaultValue>
        <note>Informs about the implementation of the service that is in force as well as about its previous implementations, if any.                </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceClassification">
        <fieldName>ServicePhaseStatusTRL</fieldName>
        <mandatory>true</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>Is used to tag the service to the full service cycle: e.g., discovery, alpha (prototype available for closed set of users), beta (service being developed while available for testing publicly TRL=6), production  (TRL= 7/8), retired (not anymore offered).                </note>
        <vocabulary isMultiSelection="true">
            <vocabularyField>eInfraCentral.beta</vocabularyField>
            <vocabularyField>eInfraCentral.production</vocabularyField>
            <vocabularyField>Not anymore offered</vocabularyField>
            <vocabularyField>TRL 1. basic principles observed</vocabularyField>
            <vocabularyField>TRL 2. technology concept formulated</vocabularyField>
            <vocabularyField>TRL 3. experimental proof of concept</vocabularyField>
            <vocabularyField>TRL 4. technology validated in lab</vocabularyField>
            <vocabularyField>TRL 5. technology validated in relevant environment</vocabularyField>
            <vocabularyField>TRL 6. technology demonstrated in relevant environment</vocabularyField>
            <vocabularyField>TRL 7. system prototype demonstration in operational environment</vocabularyField>
            <vocabularyField>TRL 8. system complete and qualified</vocabularyField>
            <vocabularyField>TRL 9. actual system proven in operational environment</vocabularyField>
        </vocabulary>
        <validator/>
        <tagging create="true" separator=".">onFieldName_onValue</tagging>
        <grouping create="true">onFieldName_onValue</grouping>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceClassification">
        <fieldName>ServiceTypeCategory</fieldName>
        <mandatory>true</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>A named group of services that offer access to the same type of resource. These are external ones that are of interest to a customer. E.g. storage, computing, networking, data, data management, identification, consultancy, etc.                </note>
        <vocabulary/>
        <validator/>
        <tagging create="true" separator=".">onFieldName_onValue</tagging>
        <grouping create="true">onFieldName_onValue</grouping>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceClassification">
        <fieldName>RelatedServices</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>Other services that are either required or commonly used with this service. If we achieve to agree on a Service ID, this will be a list of those SIDs.                </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceSupport">
        <fieldName>ServiceRequest</fieldName>
        <mandatory>true</mandatory>
        <dataType>String</dataType>
        <defaultValue>http://...</defaultValue>
        <note>Link to request the service from the service provider                </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceSupport">
        <fieldName>ServiceHelpdesk</fieldName>
        <mandatory>true</mandatory>
        <dataType>String</dataType>
        <defaultValue>http://...</defaultValue>
        <note>Link with contact to ask more information from the service provider about this service. A contact person or helpdesk within the organization must be assigned for communications, questions and issues relating to the service.                 </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceSupport">
        <fieldName>ServiceUserManual</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue>http://...</defaultValue>
        <note>Link to user manual and documentation                </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceSupport">
        <fieldName>ServiceTraining</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue>http://...</defaultValue>
        <note>Link to training information                </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceSupport">
        <fieldName>ServiceFeedback</fieldName>
        <mandatory>true</mandatory>
        <dataType>String</dataType>
        <defaultValue>http://...</defaultValue>
        <note>Link to page where customers can provide feedback on the service                </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ContractualInfo">
        <fieldName>ServicePricing</fieldName>
        <mandatory>true</mandatory>
        <dataType>String</dataType>
        <defaultValue>free</defaultValue>
        <note>Supported payment models that apply. List of sentences each of them stating the type of payment model and the restriction that applies to it.                 </note>
        <vocabulary/>
        <validator/>
        <tagging create="true" separator=".">onFieldName_onValue</tagging>
        <grouping create="true">onFieldName</grouping>
    </metadatafield>
    <metadatafield categoryref="EOSC_ContractualInfo">
        <fieldName>ServiceLevelAgreement</fieldName>
        <mandatory>true</mandatory>
        <dataType>String</dataType>
        <defaultValue>http://...</defaultValue>
        <note>Document containing information about the levels of performance that a service provider is expected to achieve. Current service agreements (SLAs) available for the service or basis for a new SLA. These should be agreements with users (not providers).                 </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ContractualInfo">
        <fieldName>ServiceOptions</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue>http://...</defaultValue>
        <note>Describes the various service options. E.g. standard, enhanced, bronze, silver, and gold, etc.                  </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ContractualInfo">
        <fieldName>TermsOfUse</fieldName>
        <mandatory>true</mandatory>
        <dataType>String</dataType>
        <defaultValue>http://...</defaultValue>
        <note>Document containing the rules, service conditions and usage policy which one must agree to abide by in order to use the service.                  </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceOperation">
        <fieldName>ServiceOwner</fieldName>
        <mandatory>true</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>This is the individual who has accountability for the whole service, from a management point of view. He will have an understanding of the service from technology through to user, and maintain an overview of the effectiveness and success of the service. All contact information should be included here. Leave blank for the service catalogue.                 </note>
        <vocabulary/>
        <validator/>
        <tagging create="true" separator=".">onFieldName_onValue</tagging>
        <grouping create="true">onFieldName_onValue</grouping>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceOperation">
        <fieldName>OperationsDocumentation</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue>http://...</defaultValue>
        <note>Leave blank for the service catalogue</note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceOperation">
        <fieldName>ServiceMonitoring</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue>http://...</defaultValue>
        <note>Leave blank for the service catalogue</note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceOperation">
        <fieldName>ServiceAccounting</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue>http://...</defaultValue>
        <note>Leave blank for the service catalogue</note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceOperation">
        <fieldName>BusinessContinuityPlan</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue>http://...</defaultValue>
        <note>Leave blank for the service catalogue</note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceOperation">
        <fieldName>DisasterRecoveryPlan</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue>http://...</defaultValue>
        <note>Leave blank for the service catalogue</note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceOperation">
        <fieldName>DecommissioningProcedure</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue>http://...</defaultValue>
        <note>Leave blank for the service catalogue</note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceOperation">
        <fieldName>MetricsAndStatistics</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue>http://...</defaultValue>
        <note>Leave blank for the service catalogue</note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceOperation">
        <fieldName>ServiceLevel1Support</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>Leave blank for the service catalogue</note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceOperation">
        <fieldName>ServiceLevel1SupportHours</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>Leave blank for the service catalogue</note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceOperation">
        <fieldName>ServiceLevel2Support</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>Leave blank for the service catalogue</note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceOperation">
        <fieldName>ServiceLevel2SupportHours</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>Leave blank for the service catalogue</note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceOperation">
        <fieldName>ServiceLevel3Support</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>Leave blank for the service catalogue</note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceOperation">
        <fieldName>ServiceLevel3SupportHours</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>Leave blank for the service catalogue</note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceOperation">
        <fieldName>ServiceMaintenanceWindow</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>Leave blank for the service catalogue</note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceOperation">
        <fieldName>ServiceAvailabilityHours</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>Leave blank for the service catalogue</note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_AdvancedServiceInfo">
        <fieldName>UseCasesAndRequirements</fieldName>
        <mandatory>false</mandatory>
        <dataType>Text</dataType>
        <defaultValue/>
        <note>Briefly outline a collection of possible scenarios related to the service which allow fulfilling the customer requirements. Leave blank for the service catalogue                </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_AdvancedServiceInfo">
        <fieldName>ServiceFeaturesActive</fieldName>
        <mandatory>false</mandatory>
        <dataType>Text</dataType>
        <defaultValue/>
        <note>Briefly outline the main current features and functionalities of the service.                </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_AdvancedServiceInfo">
        <fieldName>ServiceFeaturesUpcoming</fieldName>
        <mandatory>false</mandatory>
        <dataType>Text</dataType>
        <defaultValue/>
        <note>Briefly outline the main future features and functionalities of the service.                </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_AdvancedServiceInfo">
        <fieldName>ServiceComponents</fieldName>
        <mandatory>false</mandatory>
        <dataType>Text</dataType>
        <defaultValue/>
        <note>Core Service building blocks (components, activities etc.): The building blocks that make up the core service (minimum set of components or standard set). One component per line.  They can also be collections of the core components with different sets of additional components that are offered to customers. For example there may be a base package called ‘storage’ and an enhanced package called ‘versioned storage’.                </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_AdvancedServiceInfo">
        <fieldName>Dependencies</fieldName>
        <mandatory>false</mandatory>
        <dataType>Text</dataType>
        <defaultValue/>
        <note>In some cases a service may be built up not only from components, but also from whole other services combined with additional components. In this case there is a dependency between one service and another, and it makes more sense to list the dependency on the other service as a whole rather than simply the components within it. Dependencies can be internal services but also external services operated by other organizations.                 </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceBusinessCase">
        <fieldName>UniqueSellingPoint</fieldName>
        <mandatory>false</mandatory>
        <dataType>Text</dataType>
        <defaultValue/>
        <note>Here the most competitive, state-of-the-art, attractive from a customer point of view, attribute of the offered service should be described. Leave blank for the service catalogue                </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceBusinessCase">
        <fieldName>Competitors</fieldName>
        <mandatory>false</mandatory>
        <dataType>Text</dataType>
        <defaultValue/>
        <note>While it is important to define one's offering based on its very merit and value proposition, it is also necessary to assess competing services to be taken into consideration, e.g. even if the presented service is better and cheaper, perhaps the cost in terms of time or resources needed for customers to switch from other service providers to the new one, may be too high / unatractive.                </note>
        <vocabulary/>
        <validator/>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceBusinessCase">
        <fieldName>CostToBuild</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>How much does it cost (estimate) to initially set up the capital assets required to provide this service.                </note>
        <vocabulary/>
        <validator/>
        <grouping create="true">onFieldName_onValue</grouping>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceBusinessCase">
        <fieldName>CostToRun</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>How much does it cost (estimate) to operate this service (presented in the most appropriate unit, such as Euro/core hour, Euro/TB stored or transferred, Euro/hour of consulting, etc.)                </note>
        <vocabulary/>
        <validator/>
        <grouping create="true">onFieldName_onValue</grouping>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceBusinessCase">
        <fieldName>Pricing</fieldName>
        <mandatory>false</mandatory>
        <dataType>String</dataType>
        <defaultValue/>
        <note>Pricing is the cost perceived from (or charged to) customers. If the service is offered via a pay-per-use model where price applies, then it is likely to be the provisioning cost increased by a mark-up (profit).                </note>
        <vocabulary/>
        <validator/>
        <grouping create="true">onFieldName_onValue</grouping>
    </metadatafield>
    <metadatafield categoryref="EOSC_ServiceBusinessCase">
        <fieldName>Risks</fieldName>
        <mandatory>false</mandatory>
        <dataType>Text</dataType>
        <defaultValue/>
        <note>Risks: While many risks can be thought of, here the major ones should be listed ("major" meaning high impact and/or high probability of occuring). As an example, for a paid service, this could be lack of customers willing to pay; for an indirectly funded service, it could be not being able to meet the promises made to the funding body. It is important to approach the service per se and the service provider in a holistic manner. Understanding the risks involved allows them to be properly weighted against benefits, therefore helping the service provider to assess and decide which services are most beneficial to offer.                </note>
        <vocabulary/>
        <validator/>
        <grouping create="true">onFieldName_onValue</grouping>
    </metadatafield>
</metadataformat>


You can find all details about profiles at GCube_Resource_Catalogue#Metadata Item Profile If you need to define a new Profile you need to contact you VRE Manager.

Namespace Collection

Operation HTTP Method URL
List GET /namespaces

An example of given result is: 

[
    {
        "id": "contact",
        "title": "Contact Title",
        "name": "contact",
        "description": "This section is about Contact(s)"
    },
    {
        "id": "developer_information",
        "title": "Developer Information",
        "name": "developer_information",
        "description": "This section is about Developer(s)"
    },
    {
        "id": "extra_information",
        "title": "Extras",
        "name": "extra_information",
        "description": "This section is about Extra(s)"
    },
    {
        "id": "category1_test",
        "title": "Category 1 Title",
        "name": "category1_test",
        "description": "Category 1  description"
    },
    {
        "id": "category2_test",
        "title": "Category 2 Title",
        "name": "category2_test",
        "description": "Category 2  description"
    },
    {
        "id": "category3_test",
        "title": "Category 3 Title",
        "name": "category3_test",
        "description": "Category 3  description"
    },
    {
        "id": "category4_test",
        "title": "Category 4 Title",
        "name": "category4_test",
        "description": "Category 4  description"
    },
    {
        "id": "category5_test",
        "title": "Category 5 Title",
        "name": "category5_test",
        "description": "Category 5  description"
    },
    {
        "id": "ReportDetails",
        "title": "Report Details",
        "name": "ReportDetails",
        "description": "Report Details"
    }
]

License Collection

Operation HTTP Method URL
List GET /licenses

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

Only GCube_Resource_Catalogue#Users.2C_Roles_and_Groups CatalogueAdmin are able to invoke non-safe methods.


A group is mainly described by the following attributes (* indicate mandatory attributes):

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


Representation

An example of Group representation is: 

{
    "name": "group_name",
    "id": "fd72502e-ddfa-4121-a12a-bb42e572d649",
    "title": "Group Title",
    "description": "",
    "image_url": "",
    "state": "active",
    "extras": [],
    "created": "2018-03-22T11:48:42.612063",
    "revision_id": "0b5dda21-9bb0-4993-896b-d865e0d2f1f3"
}


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

Only [Catalogue_Admin] are able to invoke non-safe methods.

User Collection

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

Only GCube_Resource_Catalogue#Users.2C_Roles_and_Groups Catalogue Admin are able to invoke non-safe methods.

A User is mainly described by the following attributes (* indicate mandatory attributes):

  • name* (string) – the name of the user, a string between 2 and 100 characters in length, containing only lowercase alphanumeric characters, '-' and '_';
  • id (string) – the id of the user;
  • fullname (string) – the full name of the user;
  • email (string) – the email address for the user;
  • password (string) – the password of the user, a string of at least 4 characters (parameter only used to create a new user);
  • about (string) – a description of the user.


{
    "name": "luca_frosini",
    "id": " 5f5c2bc0-bcd4-460a-9548-52cd4d33b263",
    "fullname": "Luca Frosini"
}
  1. ↑ Allamaraju S. RESTful Web Services Cookbook: Solutions for Improving Scalability and Simplicity . O’Reilly. first ed. 2010
Retrieved from "https://wiki.gcube-system.org/index.php?title=GCat_Service&oldid=31800"