Resource Registry Service - Type Management

From Gcube Wiki
Revision as of 09:42, 2 July 2021 by Luca.frosini (Talk | contribs) (→‎Complex Types)

Jump to: navigation, search

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.
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 Type;
    • 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/
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.
Property list List<? extends org.gcube.informationsystem.model.reference.properties.Property> List of Objects contained inside the owner Entity and have no Header. They are reachable only by navigating the owner Entity.
Property set Set<? org.gcube.informationsystem.model.reference.properties.Property> Set (no duplicates) of Objects contained inside the owner Entity and have no Header. They are reachable only by navigating the owner Entity.
Property map Map<String, ? extends org.gcube.informationsystem.model.reference.properties.Propertyd> 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 Max and Min properties.

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 Creation

PUT /resource-registry/schema/{ Type Name }
Description

Allow to create new Entity or Relation or Embedded 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/Actor

Request Body 

{
	"name":"Actor",
	"description":"Any entity (human or machine) playing an active role.",
	"abstractType":true, /* If the Resource cannot be instantiated */
	"superclasses":["Resource"], /* Resource or any registered specialization. */
	"properties":null /* MUST be null. The Resource cannot have any property. */
}
Facet Type Creation
PUT /resource-registry/schema/ContactFacet

Request Body 

{
	"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 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 */
	}]
}
Retrieved from "https://wiki.gcube-system.org/index.php?title=Resource_Registry_Service_-_Type_Management&oldid=34171"