Plan Portability API:Brief Overview

Gerd BreiterFrank Leymann

Thomas Spatzier

2

A Caveat

• The draft of the Plan Portability has been uploaded about a year ago

• Thus, it does not reflect features the TC added over the last year– E.g. Requirements, Capabilities, Artifacts,...

• These features must be reflected in case the TC agrees to work on the API

3

A Pattern: Embracing Plan Tasks• The effects achieved by an

operation are often reflected by the return data of the operation

• Thus, this return data is passed to a post-Task of the task bound to the operation, and this post-Task uses the Plan Portability API to store this data

• From then on, the effects achieved by an operation is available in the environment in a portable manner!

• pre-Tasks can use the API to collect data required for invoking the task proper (i.e. task T)

Tpre-T post-T

Nopeffects

invokes

Plan Portability API

State of Instancesof service templates

4

API Style

• The API is a REST API• The style might be adopted to add additional

REST principles and patterns– E.g. HATEOAS, task resources,...

5

Requirements on the API• Retrieve the values of the properties of a specific instance of a node template• Retrieve the state of a specific instance of a node template• Create an instance of a service template

– This will typically be used within the build plan associated with the service template• Create an instance of a node template (considering cardinality)• Update values of particular properties and attributes of a specific node instance • Delete an node instance• Delete a service instance • Retrieve the instance identifier (URI) of a specific instance of a topology template

– This API supports queries to filter on all instances of a specific topology template– Note: This API is for convenience only. The instance identifier of a service instance may be returned

in the output message of the build plan and stored somewhere by the requestor of the build plan.• Discover instance identifiers (URIs) of instances of node templates of a specific service

instance– This API supports queries to filter node instances in a particular state only, and it allows to navigate

through the topology of the service template of the corresponding service instance in order to conveniently locate the node templates instance of which are of interest.

6

Basic Assumptions

• The base URI of each REST API is available when binding a plan– For example, during installation of a TOSCA

container the base URIs are set and stored in some environment parameters

• During binding of a task that uses one of the specified REST APIs the base URI of the API is set

7

Assumptions About Identifiers• Service Templates are uniquely identified by a URI assigned

to them at the time they are registered in a particular environment, i.e. when they are “stored” in a TOSCA container

• Service instances are identified by URIs assigned to them at instantiation time

• Node templates are identified within a service template by their unique ID attribute (as defined by the TOSCA specification)

• Instances of node templates are identified by their URI assigned to them at instantiation time

8

Supported HTTP Headers& HTTP Return Codes

• (see the draft document)

9

Retrieve Instance ID (URI) of Service Instance

Description: Retrieve the URIs of service instances created in a particular environment, satisfying certain conditionsGET /ServiceInstances?parameter_list

parameter_list: A list of parameters used to filter instance identifiers

The parameters supported are:

ServiceTemplateName: the name of the service template for which instance identifiers are to be retrieved

ServiceTemplateID: the identifier of the service template for which instance identifiers are to be retrieved

DateCreated: the date the service instance has been created CreatedBefore: the time before the service instance has been created CreatedAfter: the time after which the service instance has been created …

The parameters in query string of the request URI are ANDed.

10

Request Headers

Accept - Must be application/xml.Accept-Encoding – Supported value is gzip. If this field is not specified the response will not be encoded at all.Authorization - The credentials passed by the client to the TOSCA container to authenticate itself. Host - The base URI that the TOSCA container provides to support the specific API. TOSCA-PP-API-Version - The version of the specification of this API; must be 1.0.

11

Example

GET /ServiceInstances

?ServiceTemplateName=myWebSphereCluster

&CreatedAfter=2013-04-13&CreatedBefore=2013-06-10 HTTP/1.1

Accept: application/xml

Accept-Encoding: gzip

Authorization: Basic WalorEerq45AElk

Host: www.my-tosca-container.com

TOSCA-PP-API-Version: 1.0

12

Response

<ServiceInstances>

<ServiceInstanceURI/>*

</ServiceInstances>

The <ServiceInstances> element has the following properties:

ServiceInstanceURI: The URI representing the identifier of the qualifying service

instance.

13

Applicable HeadersApplicable Response Header Fields:Server – TOSCA container producing the response. WWW-Authenticate – Returned only if client is not authenticated.

Applicable Entity Header Fields: Content-Length - The number of octets of the enclosed entity. Content-Type - The media type of the enclosed entity. Last-Modified - Time the enclosed entity has been modified last time at the origin server.

Applicable General Header Fields:Cache-Control – Freshness period of the returned resource is provided in the max-age directive (in number of seconds; “0” indicate that resource must always be re-validated). Date – Time the message was sent. Transfer-Encoding – Encoding that has been applied to the whole message.

14

Example

HTTP/1.1 200 OKContent-Length: 212Content-Type: application/xmlLast-Modified: Tue, 1 Nov 2011 19:39:22 CET < ServiceInstances> <ServiceInstanceURI> http://www.ibm.com/websphereCluster42 </ServiceTemplateURI> <ServiceInstanceURI> http://www.ibm.com/websphereCluster4711 </ServiceTemplateURI></ServiceInstances>

...and here it get‘s clear, that the API can get more HATEOASich

15

Retrieve Instance ID (URI) of a Node Instance by Path Expression

Description: Retrieve the URIs of node instances for a particular service instance, possibly filtered via a path expression navigating from a node template or a node instance to its children.GET /NodeTemplateInstances ?ServiceInstanceID=URI &NodeTemplateID=ID &NodeInstanceID=URI &PathExpression=string &StateExpression=stringThe parameters of the query string are:ServiceInstanceID: the identifier (URI) of the service instance NodeTemplateID: the identifier (xsd:ID) of the node template the path expression starts withNodeInstanceID: the identifier (URI) of the node instance the path expression starts withPathExpression: a path expression similar to XpathStateExpression: a Boolean expression in the state property of the corresponding node template.

16

ResponseResponse Message Body:<NodeInstances> <NodeInstance NodeTemplateID="ID"? uri="anyURI"/>*</NodeInstances>

The <NodeInstances> element has the following properties:

NodeInstance: this element provides the URI of the instance qualified. Its NodeTemplateID attribute provides the value of the ID attribute of the corresponding node template. The NodeTemplateID attribute is only required in case instances of more than one node template are retrieved.

17

Example 1

The following request filters from the specific service instance …/314 all node instance identifiers reachable from all instances of node template A via relationship R1 that have a value “p1” of the property “p”.GET /NodeTemplateInstances ?ServiceInstanceID=http://www.sample.com/314 &NodeTemplateID=A &PathExpression=R1[p=p1] HTTP/1.1Accept: application/xml

Response

Only the instance with identifier “b1” has the value “p1” of property “p”. Thus, only b1 qualifies under the filter and is, thus, returned. HTTP/1.1 200 OK < NodeInstances> <NodeInstance uri="b1"/></NodeInstances>

18

Example 2

The following request filters from the specific service instance …/314 all node instance identifiers reachable from all instances of node template A via relationship R1 followed by relationship R2.GET /NodeTemplateInstances ?ServiceInstanceID=http://www.sample.com/314 &NodeTemplateID=A &PathExpression=R1/R2 HTTP/1.1Accept: application/xml

Response 2:

Both node instances, c1 and c2, reachable from the instances a1 and a2 of node template A qualify under filter.HTTP/1.1 200 OK < NodeInstances> <NodeInstance uri="c1"/> <NodeInstance uri="c2"/></NodeInstances>

19

Example 3

The following request filters from the specific service instance …/314 all node instance identifiers reachable from the particular instances a2 of node template A via relationship R1 followed by relationship R2.GET /NodeTemplateInstances ?ServiceInstanceID=http://www.sample.com/314 &NodeInstanceID=a2 &PathExpression=R1/R2 HTTP/1.1Accept: application/xml

Response 3:

Node instance c2 is reachable via the given path expression from a2 and is, thus, returned. HTTP/1.1 200 OK < NodeInstances> <NodeInstance uri="c2"/></NodeInstances>

20

Example 4

The following request filters from the specific service instance …/314 all node instance identifiers of all node templates of the topology template.GET /NodeTemplateInstances ?ServiceInstanceID=http://www.sample.com/314 HTTP/1.1Accept: application/xml

Response 4:

All node instance identifiers of all node templates are returned. Note that the node template IDs of the returned node instance identifiers are returned too to allow an identification of the node templates of each node instance identifier returned. HTTP/1.1 200 OK < NodeInstances> ... <NodeInstance NodeTemplateID="C" uri="c1"/> <NodeInstance NodeTemplateID="C" uri="c2"/> <NodeInstance NodeTemplateID="..." uri="..."/> ...</NodeInstances>

21

Example 5

The following request checks whether the node instance of ID a1 is in state “running”.GET /NodeTemplateInstances ?ServiceInstanceID=http://www.sample.com/314 &NodeInstanceID=a1 &StateExpression="state=running" HTTP/1.1Accept: application/xml

Response 5:

Because node instance of ID a1 is in fact in state ‘running’ its node instance identifier is returned. HTTP/1.1 200 OK < NodeInstances> <NodeInstance uri="a1"/></NodeInstances>

22

Example 6

The following request filters from the specific service instance …/314 all node instance identifiers reachable from all instances of node template A via relationship R1 followed by relationship R2 that are either in state ‘running’ or in state ‘terminated’.GET /NodeTemplateInstances ?ServiceInstanceID=http://www.sample.com/314 &NodeTemplateID=A &PathExpression=R1/R2 &StateExpression="state=running OR state=terminated" HTTP/1.1Accept: application/xml

Response 6:

Assume that instance c1 of node template C is starting (i.e. is does not satisfy the state expression), but instance c2 of node template C is in state ‘terminated’. Thus, only the identifier of node instance c2 is returned. HTTP/1.1 200 OK < NodeInstances> <NodeInstance uri="c2"/></NodeInstances>

23

Retrieve Artifacts of a Node Template

Description: Retrieve deployment artifacts or implementation artifacts of a node template.GET /Artifacts ?NodeTemplateID=ID &ArtifactType=[Implementation | Deployment ] &Name=string

The parameters of the query string are:

NodeTemplateID: the identifier (xsd:ID) of the node template the artifact(s) of which are to be retrieved

ArtifactType: the type of the artifact to be retrieved, i.e. whether implementation artifacts (ArtifactType=Implementation), deployment artifacts (ArtifactType=Deployment), or both are to be retrieved. For the latter case, the ArtifactType parameter is omitted.

Name: the name of the deployment artifact to be retrieved, or the operation name of the implementation artifact to be retrieved. If the Name parameter is omitted, all artifacts of the specified ArtifactType are retrieved; otherwise, only the artifact of the specified ArtifactType and Name is retrieved.

24

Response<Artifacts> <DeploymentArtifacts>? <DeploymentArtifact name="string" type="anyURI">+ artifact specific content </DeploymentArtifact> </DeploymentArtifacts> <ImplementaionArtifacts>? <ImplementationArtifact operationName="string" type="anyURI">+ artifact specific content </ImplementationArtifact> </ImplementaionArtifacts> </Artifacts>The <Artifacts> element has the following properties:• DeploymentArtifacts: this element provides deployment artifacts of the specified node template. If the Name parameter had been specified in the query string of the request the returned deployment artifact will be of that name.• ImplementationArtifacts: this element provides implementation artifacts of the specified node template. If the Name parameter had been specified in the query string of the request the returned implementation artifacts will be those of the corresponding operation name (note, that more than one implementation artifacts associated with the same operation name are allowed).

25

Example

26

Retrieve Property Values and State of a Node Instance

Description: Retrieve the values of the specified properties of a particular instance of a node template as well as its state.

GET NodeInstanceURI?PropertyList=list&State

The GET request is on the node instance resource identified by its actual NodeInstanceURI. The parameters supported are:

PropertyList: the list of parameters the values of which are to be retrieved.o In case the PropertyList is not specified at all, none of the property values are

returned.o In case no “=list” is specified for the PropertyList parameter, all property values

are returned. State: if specified the state value of the node instance is requested

o In case this parameter is not specified, no state information is returned.

27

Response<Properties> XML fragment</Properties>?<State timestamp="xsd:dateTime"> state</State>?

The response message contains a properties element or a state element.

The <Properties> element has the following properties:

o XML fragment: the XML document corresponding to the properties to be retrieved.

The <State> element contains a string representing the actual state of the node instance.o Its dateTime attribute can be used to heuristically decide on the timeliness of the

state returned.

28

Example 1

The following request retrieves the value of the IPAddress and CPUSpeed property of the node instance with the URI http://www.sample.com/appScrMember1.GET http://www.sample.com/appScrMember1 ?PropertyList=IPAddress+CPUSpeed HTTP/1.1Accept: application/xml

Response 1:

The response contains the actual values of the properties requested. HTTP/1.1 200 OKCache-Control: max-age=0 < Properties> <IPAddress>1.2.3.4</IPAddress> <CPUSpeed>2.7GHz</CPUSpeed></Properties>

29

Example 2The following request retrieves the state of the node instance of URI http://www.sample.com/appScrMember1.GET http://www.sample.com/appScrMember1?State HTTP/1.1Accept: application/xml

Response 2:

The state of the node instance is ‘running’, i.e. the corresponding value is returned. HTTP/1.1 200 OKCache-Control: max-age=0 <State>running</State>

30

Example 3The following request retrieves the values of all properties of the node instance of URI http://www.sample.com/appScrMember1.GET http://www.sample.com/appScrMember1?PropertyList HTTP/1.1Accept: application/xml

Response 3:

All property values are returned. HTTP/1.1 200 OK < Properties> <IPAddress>1.2.3.4</IPAddress> <CPUSpeed>2.7GHz</CPUSpeed> <HostName>myHost</HostName>

...</Properties>

31

Create an Instance of a Service Template

32

Response

<ServiceInstanceURI/>?

The <ServiceInstanceURI> element contains the URI representing the identifier of the service instance created. If an error occurs, no service instance URI is returned

33

Example

Example: POST /ServiceInstances ?ServiceTemplateID=http://www.sample.com/314 &NTID=A&CARD=7&NTID=B&CARD=0 HTTP/1.1Accept: application/xml

This requests the creation of an instance of the service template with the specified identifier. Node template A is to be instantiated seven times, while node template B is not to be instantiated at all.

ResonseHTTP/1.1 201 Created <ServiceInstanceURI> http://www.ibm.com/websphereCluster42</ServiceTemplateURI>

34

Create an Instance of a Node Template (i.e. a Create a Node Instance)

Description: Create an instance of a node template considering the cardinality of the node template as specified in the topology template.

This request will instantiate a node template. The number of instances to be created can be specified. Typically, this request will be used in plans different from build plans and termination plans. POST /NodeInstances ?ServiceInstanceID=URI &NodeTemplateID=ID &ParentNodeInstanceID=URI

The parameters of this request are:

ServiceInstanceID: the identifier (URI) of the service instance NodeTemplateID: the identifier (xsd:ID) of the node template the path expression

starts with ParentNodeInstanceID: the identifier of the node instance of the parent node

template. This parameter is optional; is must be specified in case the node template to be instantiated is a child of a node template of variable cardinality.

35

Response<NodeInstanceURI/>?

The <NodeInstanceURI> element contains the URI representing the identifier of the node instance created. If an error occurs, no node instance URI is returned

Status Codes:

201 Created - The request to create a new resource has been processed correctly. The Location header contains the URI of the created resource. The Content-Type header contains the media type of this resource. An ETag header might be returned too.

…

36

Example

POST /NodeInstances ?ServiceInstanceID=http://www.sample.com/271 &NodeTemplateID=C &ParentNodeInstanceID=b2 HTTP/1.1Accept: application/xml

This requests the creation of an instance of the node template C. Because the parent node template of C (with node template identifier B) is a multi-instance node, the identifier of the instance of B under which the new instance of C has to be created must be specified. In the example, the new instance of C should be created as child of node instance b2. The newly created instance of C has identifier c3.

Response:HTTP/1.1 201 Created <NodeInstance uri="c3"/>

37

Update Values of Properties and State of a Node Instance

Description: Modify the properties of a particular node instance or its state.

PUT /NodeInstanceURI?...ModifiedResource

The parameters of this request are:NodeInstanceURI: the identifier (URI) of the node instance to be modified.

The HTTP body of this request is:ModifiedResource: the modified properties or state of the node instance encoded in the HTTP body of the request.

Either the <Properties> element or the <State> element (or both) must be specified in the HTTP body.

HTTP Body:

<Properties> XML fragment</Properties>?<State> state</State>?

The HTTP body contains a properties element or a state element.

The <Properties> element has the following value:

o XML fragment: the XML document corresponding to the properties to be substituted. This XML document is an instance of the node type properties element of the corresponding node type. Thus, the processor of this request will validate the XML document provided; in case of the validation resulting in an error, a corresponding HTTP error code will be returned.

The <State> element contains a string representing the modified state of the node instance.

38

ExamplePUT http://www.sample.com/appScrMember1 HTTP/1.1Content-Type: application/xml... 

< Properties> <IPAddress>3.1.4.1</IPAddress> <CPUSpeed>2.0GHz</CPUSpeed> <HostName>ThomasHost</HostName>

...</Properties><State>running</State>

HTTP/1.1 200 OK

39

Delete a Node Instance

Description: Delete an instance of a node template. DELETE NodeInstanceURI

The node instance identified by the specified URI is deleted. In case the node instance to be deleted is a child of a multi instance node and the deletion would result in a violation of the minimum number of instances of the parent node, the deletion is not performed and a corresponding HTTP error is returned.

40

Delete a Service Instance

Description: Delete an instance of a service template. DELETE ServiceInstanceURI

The service instance identified by the specified URI is deleted.

41

END OF PRESENTATION