Difference between revisions of "Resource Registry Service - Type Management"
Luca.frosini (Talk | contribs) (→Facet Type Creation) |
Luca.frosini (Talk | contribs) (→Facet Type Creation) |
||
Line 344: | Line 344: | ||
{ | { | ||
"@class": "FacetType", | "@class": "FacetType", | ||
− | "header": | + | "header": null, |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
"name": "ContactFacet", | "name": "ContactFacet", | ||
"description": "ContactFacet captures information on a point of contact for the resource, i.e., a person or a department serving as the coordinator or focal point of information concerning the resource.", | "description": "ContactFacet captures information on a point of contact for the resource, i.e., a person or a department serving as the coordinator or focal point of information concerning the resource.", |
Revision as of 10:00, 2 July 2021
These sections provide information regarding how to interact with Resource Registry Service for Type Management. REST API are presented for each functionality.
Please note that the provided examples can intentionally hide some details in the response to avoid unneeded complexity.
Type Management
Type Management is responsible for managing the instantiation of the IS Model by allowing the definition of entities, relations and embedded types and their schema.
The exposed APIs are:
- Create: allows to create a new Type;
- Exists: allows to check if a Type exists;
- Read: allows to read a Type. This API allows also the listing of type and its subtypes by indicating hte query parameter polymorphic=true.
By indicating the polimorphic parameter and as {TYPE_NAME} on of the base type of the IS Model (i.e. Resource, Facet, IsRelatedTo, ConsistsOf), it is possibile to list all the types of such base type.
Type Collection
Operation | HTTP Method | URL |
---|---|---|
Create | PUT | /types/{TYPE_NAME}
|
Exists | HEAD | /types/{TYPE_NAME}
|
Read | GET | /types/{TYPE_NAME}[?polymorphic=false]
|
Type Definition
Any Type is described by the following attributes:
- name (String): Type Name
- description (String): The description of the Type.
default=null
. - abstractType (Boolean): Indicate if the type is abstract so that it cannot be instantiated. In other words, only subtypes of this type can be instantiated.
default=false
. - superclasses (List<String>): The list of all supertypes of this type. Multiple Inheritance is supported.
- properties: any types, except Resource and its specialisation, includes a properties array [List]. Any #Property is described by a set of attributes.
- version: the actual version of the type;
- changelog: the history of changes in the type representation. It is an object containing properties with version as key and the change description as values.
Any Relation has two additional mandatory attributes:
- source: indicate the required source type to instantiate such relation;
- target: indicate the required target type to instantiate such relation.
Any Resource instead of properties expose two arrays:
- facets: this array defines which Facet types describe the resource and which ConsistsOf relation type must be used to connect the facet instance;
- resources: this array defines which other Resource types could be related to the defined type and which IsRelatedTo relation type could be used to connect the instances of them. The array contains only the outbound relations.
Each element of the ’facets’ and ’resources’ arrays contained in the Resource definition is composed of six attributes (* indicates a mandatory attribute):
- source*: it is always the name of the defined type [String];
- relation*: the relation type name to be used to connect the source type to the target type [String];
- target*: the target type name of the relation [String];
- description: the description of the reason why the source and the target should be related [String, default=null];
- max: the upper bound number of relations between the source and target types (null means unbounded) [Integer, default=null];
- min: the lower bound number of relations between the source and target types (null is the same as zero which means that the relation is optional). Optional relations are specified as to provide suggestion to whom is interested in instantiating the resource type [Integer, default=null].
Property
Any Property is described by the following attributes:
- name*: the property name [String];
- type*: The Type of the Property (e.g. String, Integer, ...). See Property Types;
- description: the description of the property [String, default=null];
- mandatory: indicate if the property is mandatory or not [String, default=false];
- readOnly: the property cannot change its value [Boolean, default=false];
- notNull: whether the property must assume a value diverse from ’null’ or not [Boolean, default=false];
- max: whether the property can be limited to a maximum value [Integer, default=null];
- min: whether the property can be limited to a minimum value [Integer, default=null];
- regex: a regular expression to validate the property value [String, default=null]. A good online tool for regex is available at https://regex101.com/
Property Types
Basic Types
Type | Java type | Description |
---|---|---|
Boolean | java.lang.Boolean or boolean
|
Handles only the values True or False. |
Integer | java.lang.Integer or int or java.math.BigInteger
|
32-bit signed Integers. |
Short | java.lang.Short or short
|
Small 16-bit signed integers. |
Long | java.lang.Long or long
|
Big 64-bit signed integers. |
Float | java.lang.Float or float
|
Decimal numbers. |
Double | java.lang.Double or double
|
Decimal numbers with high precision. |
Date | java.util.Date
|
Any date with the precision up to milliseconds. |
String | java.lang.String
|
Any string as alphanumeric sequence of chars. |
Property | ? extends org.gcube.informationsystem.model.reference.properties.Property
|
This is an Object contained inside the owner Entity and has no Header. It is reachable only by navigating the owner Entity. |
|
List<? extends org.gcube.informationsystem.model.reference.properties.Property> |
|
|
Set<? org.gcube.informationsystem.model.reference.properties.Property> |
|
Map<String,Property> | Map<String, ? extends org.gcube.informationsystem.model.reference.properties.Property>
|
Map of Objects contained inside the owner Entity and have no Header. They are reachable only by navigating the owner Entity. |
Byte | java.lang.Byte or byte
|
Single byte. useful to store small 8-bit signed integers. |
Binary | java.lang.Byte[] or byte[]
|
Can contain any value as byte array. |
Derived Types
The following are obtained using a String as real type and adding a validation regex.
Type | Java type | Description |
---|---|---|
Enum | java.lang.Enum or enum
|
by default it is represented using the String representation of the Enum. So that the primitive type used will be String. The enumeration is checked by setting Regexpr property. The Regular Expression is auto-generated and it will be something like ^(FIRST-ENUM-STRING_REPRESENTATION|SECOND-ENUM-STRING_REPRESENTATION|...|LAST_ENUM_STRING_REPRESENTATION)$ .
Otherwise (if indicated using an annotation), it can be represented using the Integer value of the Enum. So that the primitive type used will be Integer. The enumeration is checked using |
UUID | java.util.UUID
|
String representation of the UUID. The check is obtained using the regular expression ^([a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}){1}$
|
URL | java.net.URL
|
String representation of the URL. No check actually. |
URI | java.net.URI
|
String representation of the URI. No check actually. |
TypeVersion | org.gcube.informationsystem.utils.TypeVersion
|
A type representing and validating a version in the following format X.X.X Major(Integer).Minor(Integer).Revision(Integer) (e.g 1.0.0, 2.3.0, 2.0.1). The check is obtained using the regular expression ^[1-9][0-9]{0,}\.(0|([1-9][0-9]{0,}))\.(0|([1-9][0-9]{0,}))$ .
|
Complex Types
Any property defined by composing basic types derives from Property type.
Type Representation Example
An example of representation of Facet type
{ "@class": "FacetType", "header": { "@class": "Header", "uuid": "0d5167fa-dade-40e9-a961-4ca0c20aec85", "createdBy": "luca.frosini", "creationTime": "2021-06-30 09:37:53.328 +0000", "lastUpdateBy": "luca.frosini", "lastUpdateTime": "2021-06-30 09:37:53.328 +0000" }, "name": "Facet", "description": "This is the base class for Facets", "abstract": true, "version": "1.0.0", "changelog": { "1.0.0": "First Version" } }
Type Creation
PUT /resource-registry/schema/{TYPE_NAME}
Description
Allow creating new Entity or Relation or Property Type.
Parameters
Name | Type | Required | Description |
---|---|---|---|
Type Name | String | true | The name of the new type to create |
Responses
Code | Type | Description |
---|---|---|
200 | String | The json representation of the newly created type (which is the same of the request) |
Examples
Resource Type Creation
PUT /resource-registry/schema/EService
Request Body
{ "@class": "ResourceType", "header": null, "name": "EService", "description": "EService is any running service that is registered in the infrastructure and made available by an access point.", "superClasses": [ "Service" ], "facets": [ { "@class": "LinkedEntity", "source": "EService", "relation": "IsIdentifiedBy", "target": "SoftwareFacet", "description": "The main software enabling the EService capabilities.", "min": 1, "max": 1 }, { "@class": "LinkedEntity", "source": "EService", "relation": "ConsistsOf", "target": "SoftwareFacet", "description": "Software available in the EService environment that characterizes the specific EService instance.", "min": 0, "max": null }, { "@class": "LinkedEntity", "source": "EService", "relation": "ConsistsOf", "target": "AccessPointFacet", "description": "Identify the endpoints of the EService.", "min": 1, "max": null }, { "@class": "LinkedEntity", "source": "EService", "relation": "ConsistsOf", "target": "EventFacet", "description": "Events characterising the current status and lifecycle of the service, e.g. ActivationTime, DeploymentTime.", "min": 1, "max": null }, { "@class": "LinkedEntity", "source": "EService", "relation": "ConsistsOf", "target": "StateFacet", "description": "The current status of the EService, e.g. STARTED, ready, down, failed.", "min": 1, "max": 1 }, { "@class": "LinkedEntity", "source": "EService", "relation": "ConsistsOf", "target": "LicenseFacet", "description": "The specific terms of use governing the exploitation of the EService.", "min": 0, "max": null } ], "resources": [ { "@class": "LinkedEntity", "source": "EService", "relation": "Discovers", "target": "EService", "description": "A reference to any other EService, the EService instance is discovering through query on IS.", "min": 0, "max": null }, { "@class": "LinkedEntity", "source": "EService", "relation": "Uses", "target": "EService", "description": "A reference to any other EService, the EService instance is invoking.", "min": 0, "max": null } ], "abstract": false, "version": "1.0.0", "changelog": { "1.0.0": "First Version" } }
Facet Type Creation
PUT /resource-registry/schema/ContactFacet
Request Body
{ "@class": "FacetType", "header": null, "name": "ContactFacet", "description": "ContactFacet captures information on a point of contact for the resource, i.e., a person or a department serving as the coordinator or focal point of information concerning the resource.", "superClasses": [ "Facet" ], "properties": [ { "@class": "PropertyDefinition", "name": "eMail", "description": "Email address", "mandatory": true, "readonly": false, "notnull": true, "max": null, "min": null, "regexp": "^[a-z0-9._%+-]{1,128}@[a-z0-9.-]{1,128}$", "type": "String" }, { "@class": "PropertyDefinition", "name": "middleName", "description": "Middle Name", "mandatory": false, "readonly": false, "notnull": false, "max": null, "min": null, "regexp": null, "type": "String" }, { "@class": "PropertyDefinition", "name": "surname", "description": "Surname", "mandatory": true, "readonly": false, "notnull": true, "max": null, "min": null, "regexp": null, "type": "String" }, { "@class": "PropertyDefinition", "name": "name", "description": "First Name", "mandatory": true, "readonly": false, "notnull": true, "max": null, "min": null, "regexp": null, "type": "String" }, { "@class": "PropertyDefinition", "name": "title", "description": "A name describing the profession or marital status of the point of contact. e.g., Dr, Mrs, Mr.", "mandatory": false, "readonly": false, "notnull": false, "max": null, "min": null, "regexp": null, "type": "String" } ], "abstract": false, "version": "1.0.0", "changelog": { "1.0.0": "First Version" } }
IsRelatedTo Type Creation
PUT /resource-registry/schema/Hosts
Request Body
{ "name":"Hosts", "description": "…”, "abstractType":false, "superclasses":["IsRelatedTo"], "properties":[] }
ConsistsOf Type Creation
PUT /resource-registry/schema/HasContact
Request Body
{ "name":"HasContact", "description":"", "abstractType":true, "superclasses":["ConsistsOf"], "properties":[] }
Property Type Creation
PUT /resource-registry/schema/AccessPolicy
Request Body
{ "name":"AccessPolicy", "description":"", "abstractType":false, "superclasses":["Embedded"], "properties":[{ "name":"policy", "description":"", "mandatory":false, "readonly":false, "notnull":false, "max":null, "min":null, "regexpr":null, "linkedType":null, "linkedClass":”ValueSchema”, "type": 9 /* Embedded */ },{ "name":"note", "description":"", "mandatory": false, "readonly":false, "notnull":false, "max":null, "min":null, "regexpr":null, "linkedType":null, "linkedClass":null, "type":7 /* String */ }] }
Read Type Definition
GET /resource-registry/schema/{ Type Name }
Description
Allow to read Type Definition
Parameters
Name | Type | Required | Description |
---|---|---|---|
Type Name | String | true | The name of the type you want to retrieve the definition |
Responses
Code | Type | Description |
---|---|---|
200 | String | The json representation of the newly created type |
Examples
Resource Type
GET /resource-registry/schema/Actor
Response
{ "name":"Actor", "description":"Any entity (human or machine) playing an active role.", "abstractType":true, "superclasses":["Resource"], "properties":null }
Facet Type
GET /resource-registry/schema/ContactFacet
Response
{ "name":"ContactFacet", "description":"This facet is expected to capture contact information", "abstractType": false, "superclasses":["Facet"], "properties":[ { "name":"name", "description":"First Name", "mandatory":true, "readonly":false, "notnull":true, "max":null, "min":null, "regexpr":null, "linkedType":null, "linkedClass":null, "type":7 /* String*/ },{ "name":"eMail", "description": "A restricted range of RFC‑822 compliant email address. ... ", "mandatory":true, "readonly":false, "notnull":true, "max":null, "min":null, "regexpr":"^[a-z0-9._%+-]{1,128}@[a-z0-9.-]{1,128}$", "linkedType":null, "linkedClass":null, "type":7 /* String */ } ] }
IsRelatedTo Type
GET /resource-registry/schema/Hosts
Response
{ "name":"Hosts", "description": "…”, "abstractType":false, "superclasses":["IsRelatedTo"], "properties":[] }
ConsistsOf Type
GET /resource-registry/schema/HasContact
Response
{ "name":"HasContact", "description":"", "abstractType":true, "superclasses":["ConsistsOf"], "properties":[] }
Property Type
GET /resource-registry/schema/AccessPolicy
Response
{ "name":"AccessPolicy", "description":"", "abstractType":false, "superclasses":["Embedded"], "properties":[{ "name":"policy", "description":"", "mandatory":false, "readonly":false, "notnull":false, "max":null, "min":null, "regexpr":null, "linkedType":null, "linkedClass":”ValueSchema”, "type": 9 /* Embedded */ },{ "name":"note", "description":"", "mandatory": false, "readonly":false, "notnull":false, "max":null, "min":null, "regexpr":null, "linkedType":null, "linkedClass":null, "type":7 /* String */ }] }