Difference between revisions of "Resource Registry Service - Context Management"

From Gcube Wiki
Jump to: navigation, search
Line 5: Line 5:
 
|}
 
|}
  
−
This sections provide information regarding how to interact with [[Information System Resource Registry#Resource_Registry Service | Resource Registry Service]]. REST and JAVA API are presented for each functionality.
+
This sections provide information regarding how to interact with [[Information System Resource Registry#Resource_Registry Service | Resource Registry Service]] for Context and Schema Port Type.  
 +
REST API are presented for each functionality.
 +
Java libraries for these port types are currently under development and will be document as soon as available.
  
 
Please note that the provided examples can intentionally hide some details in the response to avoid unneeded complexity.
 
Please note that the provided examples can intentionally hide some details in the response to avoid unneeded complexity.

Revision as of 17:54, 8 November 2017

This sections provide information regarding how to interact with Resource Registry Service for Context and Schema Port Type. REST API are presented for each functionality. Java libraries for these port types are currently under development and will be document as soon as available.

Please note that the provided examples can intentionally hide some details in the response to avoid unneeded complexity.

Context Management

It is responsible for managing Context belonging to the same Application Domain.

Security configuration based on Authorization Framework make this port type accessible only from Resource Manager. In other words no others client is allowed to manage Context rather than Resource Manager.

Context requirements:

  • No predefined number of levels.
  • Possibility to change the name of the Context with no impact for any component.
  • Possibility to move a Context from a parent Context to another.

Available Methods:

Any action made to Contexts succeed if the following requirements are guaranteed:

  • Two Context with same name can exist but only if they have different parents. The operation which will try to obtain a Context with the same name to the same parent will fails with no effect.
  • Any operation made in any Context has effect only to the Context. In other words, there will be no effect on the associated Entity and Relations.

At time of writing this port type is only accessible by using REST API. Resource Registry Context Client (java client) is under development.

Create

PUT /resource-registry/context

Description

Create new Context as child of another Context (if any).

Parameters

Name Type Required Description
name String true The name of the context.
parentContextId String (UUID) false The UUID of the parent Context if any

Responses

Code Type Description
200 String The json representation of the Context.

Examples

Create a new Context with name gcube with no parent. It is a ROOT Context.

Request URL 

PUT /resource-registry/context?name=gcube

Response Body 

{
	"@class":"Context",
	"name":"gcube",
	"header": {
		"@class":"Header",
		"uuid":"2705dd32-c857-444b-818a-3ec69e339e5d",
		"creator":"luca.frosini",
		"lastUpdater":"luca.frosini",
		"creationTime":"2017-03-17 11:47:55",
		"lastUpdateTime":"2017-03-17 11:47:55"
	}
}


Create a new Context with name devsec as child of Context with UUID 2705dd32-c857-444b-818a-3ec69e339e5d (gcube)

Request URL 

/resource-registry/context?name=devsec&parentContextId=2705dd32-c857-444b-818a-3ec69e339e5d

Response Body 

{
	"@class":"Context",
	"name":"devsec",
	"header": {
		"@class":"Header",
		"uuid":"30f6254c-c87a-451e-bc0f-7cfcbd94a84a",
		"creator":"luca.frosini",
		"lastUpdater":"luca.frosini",
		"creationTime":"2017-03-17 11:47:56",
		"lastUpdateTime":"2017-03-17 11:47:56"
	}
}


Create a new Context with name devVRE as child of Context with UUID 30f6254c-c87a-451e-bc0f-7cfcbd94a84a (devsec)

Request URL 

/resource-registry/context?name=devVRE&parentContextId=30f6254c-c87a-451e-bc0f-7cfcbd94a84a

Response Body 

{
	"@class":"Context",
	"name":"devVRE",
	"header": {
		"@class":"Header",
		"uuid":"9d73d3bd-1873-490c-b0a7-e3c0da11ad52",
		"lastUpdater":"luca.frosini",
		"creator":"luca.frosini",
		"creationTime":"2017-03-17 11:47:57",
		"lastUpdateTime":"2017-03-17 11:47:57"
	}
}

If you try to create again a Context with name gcube with no parent. You will obtain a 400 Bad Request HTTP error

Request URL 

PUT /resource-registry/context?name=gcube

Response Body 

{
    "@class": "ContextCreationException",
    "message": "A root context with the same name (gcube) already exist"
}

This will happen anytime you try to create a context with the same name, having the same parent, of an existing Context.

Read

GET /resource-registry/context/{UUID}

Description

Return the definition of the Context identified by the UUID provided as path parameter.

Parameters

Name Type Required Description
{Path Parameter} String (UUID) true The UUID of the target context.

Responses

Code Type Description
200 String The json representation of the context.

Examples

Read the Context having UUID 9d73d3bd-1873-490c-b0a7-e3c0da11ad52

Request URL 

GET /resource-registry/context/9d73d3bd-1873-490c-b0a7-e3c0da11ad52

Response Body 

{
	"@class":"Context",
	"name":"devVRE",
	"header": {
		"@class":"Header",
		"uuid":"9d73d3bd-1873-490c-b0a7-e3c0da11ad52",
		"creator":"luca.frosini",
		"lastUpdater":"luca.frosini",
		"creationTime":"2017-03-17 11:47:56",
		"lastUpdateTime":"2017-03-17 11:52:56"
	}
}

Rename

POST /resource-registry/context/rename/{UUID}

Description

Rename a Context identified by the UUID provided as path parameter to the new name provided as query parameter.

Parameters

Name Type Required Description
{Path Parameter} String (UUID) true The UUID of the target context.
name String true The new name of the target context.

Responses

Code Type Description
200 String The json representation of the context.

Examples

Rename a Context 9d73d3bd-1873-490c-b0a7-e3c0da11ad52 (was devVRE) to the new name devNext.

Request URL 

POST /resource-registry/context/rename/9d73d3bd-1873-490c-b0a7-e3c0da11ad52?name=devNext

Response Body 

{
	"@class":"Context",
	"name":"devNext",
	"header": {
		"@class":"Header",
		"uuid":"9d73d3bd-1873-490c-b0a7-e3c0da11ad52",
		"creator":"luca.frosini",
		"lastUpdater":"luca.frosini",
		"creationTime":"2017-03-17 11:47:56",
		"lastUpdateTime":"2017-03-17 11:52:56"
	}
}

Move

POST /resource-registry/context/move/{{UUID}}

Description

Move a Context identified by the UUID provided as path parameter as child of the Context provided as query parameter.

Parameters

Name Type Required Description
{Path Parameter} String (UUID) true The UUID of the target Context
parentContextId String (UUID) true The parent Context UUID

Responses

Code Type Description
200 String The json representation of the context.

Examples

Rename a Context 9d73d3bd-1873-490c-b0a7-e3c0da11ad52 as child of the Context 761d9e99-a4dc-4838-9b16-4bf73813b625

Request URL 

POST /resource-registry/context/move/9d73d3bd-1873-490c-b0a7-e3c0da11ad52?parentContextId=761d9e99-a4dc-4838-9b16-4bf73813b625

Response Body 

{
	"@class":"Context",
	"name":"devNext"
	"header": {
		"@class":"Header",
		"uuid":"9d73d3bd-1873-490c-b0a7-e3c0da11ad52",
		"creator":"luca.frosini",
		"lastUpdater":"luca.frosini",
		"creationTime":"2017-03-17 11:47:56",
		"lastUpdateTime":"2017-03-17 11:52:56"
	}
}

Delete

DELETE /resource-registry/context/{{UUID}}

Description

Delete the Context identified by the UUID provided as path parameter.

Parameters

Name Type Required Description
{Path Parameter} String (UUID) true The UUID of the target Context

Responses

Code Type Description
200 String NO CONTENT

Examples

Delete the Context having UUID 9d73d3bd-1873-490c-b0a7-e3c0da11ad52

Request URL 

DELETE /resource-registry/context/9d73d3bd-1873-490c-b0a7-e3c0da11ad52

Schema Management

At time of writing this port type is only accessible by using REST API. Resource Registry Schema Client (java client) is under development.

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 instatiated. In other words only subtypes of this type can be isntantiated. default=false.
  • superclasses (List<String>): The list of all supertypes of this type. Multiple Inheritance is supported.
  • Zero o more Properties

Property

Any Property is described by the following attributes:

  • name : Property Name
  • type : The Type of the Property (e.g. String, Integer, ...). See Property Type
  • description : The description of the Property. default=null.
  • mandatory : Indicate if the Property is mandatory. default=false.
  • readOnly : The Property cannot change its value. default=false.
  • notNull : Whether the property must assume a value diverse from 'null' or not. default=false
  • max : default=null
  • min : default=null
  • regexpr : A Regular Expression to validate the property value, default=null. A good online tool for regex is avalable at https://regex101.com/
Property Type Mapping

Property Type are mapped to and integer to be used in property definition:

Type binder is defined here: [1]

Type Integer Mapping Java type Description
Boolean 0 java.lang.Boolean or boolean Handles only the values True or False.
Integer 1 java.lang.Integer or int or java.math.BigInteger 32-bit signed Integers.
Short 2 java.lang.Short or short Small 16-bit signed integers.
Long 3 java.lang.Long or long Big 64-bit signed integers.
Float 4 java.lang.Float or float Decimal numbers
Double 5 java.lang.Double or double Decimal numbers with high precision.
Date 6 java.util.Date Any date with the precision up to milliseconds.
String 7 java.lang.String Any string as alphanumeric sequence of chars.
Binary 8 java.lang.Byte[] or byte[] Can contain any value as byte array.
Embedded 9 ? extends org.gcube.informationsystem.model.embedded.Embedded This is an Object contained inside the owner Entity and has no Header. It is reachable only by navigating the owner Entity.
Embedded list 10 List<? extends org.gcube.informationsystem.model.embedded.Embedded> List of Objects contained inside the owner Entity and have no Header. They are reachable only by navigating the owner Entity.
Embedded set 11 Set<? extends org.gcube.informationsystem.model.embedded.Embedded> Set (no duplicates) of Objects contained inside the owner Entity and have no Header. They are reachable only by navigating the owner Entity.
Embedded map 12 Map<String, ? extends org.gcube.informationsystem.model.embedded.Embedded> Map of Objects contained inside the owner Entity and have no Header. They are reachable only by navigating the owner Entity.
Byte 17 java.lang.Byte or byte Single byte. usesful to store small 8-bit signed integers.

Type Creation

PUT /resource-registry/schema/{{type}}

Description

Allow to create new Entity or Relation or Embedded Type.

Parameters

Name Type Required Description
type 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":[]
}
Embedded 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}}

Description

Allow to read Type Definition

Parameters

Name Type Required Description
type 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":[]
}
Embedded 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_-_Context_Management&oldid=29947"