We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
PaaS Open RESTful API Specification - FIWARE Forge Wiki

PaaS Open RESTful API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the PaaS Manager API

Please check the FI-WARE Open Specifications Legal Notice to understand the rights to use FI-WARE Open Specifications.

PaaS Manager API Core

The PaaS Manager API is a RESTful, resource-oriented API accessed via HTTP/HTTPS that uses XML-based and/or JSON-based representations for information interchange that provide management of software in the Cloud. The PaaS Manager offers some mechanisms for creating environment for deploying application. The environment involves both the virtual machines and the software required.

Intended Audience

This specification is intended for both software developers and final users. For the former, this document provides a full specification about a environment catalogue. For the latter, this specification indicates the interface to be provided in order to clients to manage their environment in the testbed as well as deploying applications on top of these environments. To use this information, the reader should firstly have a general understanding of thePaaS Manager GE and also be familiar with:

API Change History

This version of the PaaS Manager API Guide replaces and obsoletes all previous versions. The most recent changes are described in the table below:

Version Changes Summary
Nov 14, 2012
  • First version of the PaaS Manager API, API uses for managing environments and applications in the Cloud.
Dic 18, 2013
  • Second version of the PaaS Manager API including network and regions in the tier definition


How to Read This Document

In the whole document the assumption is taken that the reader is familiarized with REST architecture style. Along the document, some special notations are applied to differentiate some special words or concepts. The following list summarizes these special notations.

  • A bold, mono-spaced font is used to represent code or logical entities, e.g., HTTP method (GET, PUT, POST, DELETE).
  • An italic font is used to represent document titles or some other kind of special text, e.g., URI.
  • The variables are represented between brackets, e.g. {id} and in italic font. When the reader find it, can change it by any value.

For a description of some terms used along this document, see [1].

Additional Resources

You can download the most current version of this document from the FIWARE API specification selecting PDF Version from the Toolbox menu (left side), which will generate the file to download it. For more details about the PaaS Manager that this API is based upon, please refer to Cloud Hosting.

General PaaS Manager API Information

Resources Summary

A diagram, in which the different URNs that can be used in the API, is shown here. The URL for accessing to the API is something like: http://IP_host:port/paasmanager/rest.

PaaS Manager API resources


PaaS Manager Open RESTful API resources summary

Authentication

It is using Oauth for authentication. It means including the X-Auth-Token header with a valid token like it

 X-Auth-Token: X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

Representation Format

The PaaS Manager API resources are represented by hypertext that allows each resource to reference other related resources. More concisely, XML or JSON format are used for resource representation and URLs are used for referencing other resources by default. The request format is specified using the Content-Type header and is required for operations that have a request body. The response format can be specified in requests using either the Accept header with values application/json or application/xml or adding an .xml or .json extension to the request URI. In the following examples we can see the different options in order to represent format.

POST /catalog/environment HTTP/1.1
Host: paasmanager.tid.org
Content-Type: application/json
Accept: application/xml
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb


POST /catalog/environment HTTP/1.1
Host: paasmanager.tid.org
Content-Type: application/xml
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb


POST /catalog/environment HTTP/1.1
Host: paasmanager.tid.org
Content-Type: application/json
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb


Representation Transport

Resource representation is transmitted between client and server by using HTTP 1.1 protocol, as defined by IETF RFC-2616. Each time an HTTP request contains payload, a Content-Type header shall be used to specify the MIME type of wrapped representation. In addition, both client and server may use as many HTTP headers as they consider necessary.

Resource Identification

API consumer must indicate the resource identifier while invoking a GET, PUT, POST or DELETE operation. PaaS Manager API combines both identification and location by terms of URL. Each invocation provides the URL of the target resource along the verb and any required input data. That URL is used to identify unambiguously the resource. For HTTP transport, this is made using the mechanisms described by HTTP protocol specification as defined by IETF RFC-2616.

PaaS Manager API does not enforce any determined URL pattern to identify its resources. Anyway the PaaS Manager API follows the HATEOAS principle (Hypermedia As The Engine Of Application State). This means that resource representation contains the URLs of the related resources (e.g., book representation contains hyperlinks to its chapters; chapter representation contains hyperlinks to its pages...). API consumer obtains the VDC representation as its following point, which in turn provides hyperlinks that directly or indirectly take to other resources like Services and/or Servers.

PaaS Manager API entities provide an instance identifier property (instance ID). This property is used to identify unambiguously the entity but not the REST resource used to manage it, which is identified by its URL as described above (although this URL can contain the instance ID). It is common that most implementations make use of instance ID to compose the URL (e.g., the book with instance ID 1492 could be represented by resource http://.../book/1492), but such an assumption should not be taken by API consumer to obtain the resource URL from its instance ID.

Links and References

Resources often lead to refer to other resources. In those cases, we have to provide an ID or an URL to a remote resource.

Paginated Collections (Optional)

In order to reduce the load on the service, we can decide to limit the number of elements to return when it is too big. In order to do it, we use the limit, which is the maximum number of element to return, and last parameter, which was the last element to see. In the response JSON, we include an atom "next" links to follow to the next group of data. The last page in the list will not contain a "next" link. If there is an over limit error, the API will return a 413 message (over limit error) or 404 message (item not found error).

Efficient Polling with the Changes-Since Parameter (Optional)

In this case we can specify the parameter changes-since in a GET method in order that the response will give us only the changed information from the previous request specified through a dateTime format ISO 8601 (2011-01-24T17:08Z).

Limits

n.a

Versions

This is the first version.

Extensions

No apply yet.

Faults

The error code is returned in the body of the response for convenience. The message section returns a human-readable message that is appropriate for display to the end user. The details section is optional and may contain information—for example, a stack trace—to assist in tracking down an error. The detail section may or may not be appropriate for display to an end user.

PaaS Manager API Faults
Fault Element Associated Error Codes Description
Fault 500, 400, other codes possible Error in the operation
serviceUnavailable 503 The service is not available
unauthorized 401 You are not authorized to access to that operation. The token is not correct.
forbidden 403 It is forbidden
badRequest 400 The request has not been done correctly
badMediaType 415 The payload media is not correct
itemNotFound 404 It is not exist


Besides the previous errors, when there is a error in the PaaS Manager operation, the PaaS Managerprints this error in the task result although the request error code is 200. In this case, the task status is ERROR and there is a message indicating its error message.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<task href="http:/130.206.80.112:8080/paasmanager/rest/org/{org-id}/vdc/{vdc-id}/task/{task-id}" startTime="2012-11-08T09:13:18.311+01:00" status="ERROR">
  <description>Deploy environment {emvironment-name}</description>
  <vdc>{vdc-id}</vdc>
</task>

In this case the main controlled exceptions are:

  1. InvalidApplicationReleaseException: The application release provided in the payload is not correct.
  2. InvalidEnvironmentRequestException: The environment information is not right.
  3. InvalidProductInstanceRequestException: The information about the product instance is created incorrectly
  4. EnvironmentInstanceNotFoundException: The environment instance is not found.
  5. ApplicationInstanceNotFoundException: The application instance does not exist
  6. ProductReleaseNotFoundException: The product release is not found.
  7. ProductInstallatorException: There is a problem to install the product
  8. ApplicationInstallatorException: There is a problem to install the application
  9. IPNotRetrievedException: There is a problem to obtain the IP from the VM
  10. VMStatusNotRetrievedException: There is a problem to obtain the status of the VM
  11. InfrastructureException: There is a problem with a operation in the IaaS level
  12. PaasManagerServerRuntimeException: There is an problem in the PaaS Manager works

API Operations

In this section we go in depth for each operation. These operations have been described in the PaaS Manager Architecture. The FIWARE programmer guide will also provide examples of how to use the API. In this page, only XML examples are going to be provided.

The PaaS Manager API is divided among two functionalities:

  • The catalogue of available environments to be deployed.
  • The provisioning of environments and applications.

Due to it, we make two main divisions in the API explanation.

Environment Catalogue

It involves the catalogue of environments to be deployed.

List Environments in the catalogue

Verb URI Description
GET /paasmanager/rest/catalog/environment Lists all Environments in the catalogue.

Normal Response Code(s): 200, 203

Error Response Code(s): identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404)

This operation does not require a request body.

This operation lists the environments stored in the catalogue. The following example shows an XML response for the list Environment API operation. It is possible to see it contains a list of tiers including products to be installed.

<environmentDtoes>
  <environment>
  <name>{emvironment-name}</name>
     <tiers>
        <tier>
           <initial_number_instances>1</initial_number_instances>
           <maximum_number_instances>1</maximum_number_instances>
           <minimum_number_instances>1</minimum_number_instances>
           <name>{tier-id}</name>               
           <productReleases>                  
              <product>postgresql</product>
              <version>0.0.3</version>
              <withArtifact>true</withArtifact> 
              <productType> 
                 <id>5</id>
                 <name>Database</name>  
              </productType> 
           </productReleases>
                     ...
       </tier>   
    </tiers>
  </environment>
  <environment>
  <name>{emvironment-name}</name>
     <tiers>
        <tier>
          ...
        <tier>
     </tiers>
  </environment>
</environmentDtoes>

Add a Environment to the catalogue

Verb URI Description
POST /paasmanager/rest/catalog/environment Add the Environment into the PaaS Manager's catalog. If the Environment already exists, then it updates it. If not, this method also creates the environment.

Normal Response Code(s): 200 Ok

Error Response Code(s): identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), badMediaType (415)

This operation stores a new environment in the catalogue. This call creates a new environment in the catalogue and does not return any response body.

<?xml version="1.0" encoding="UTF-8"?>
<environment>
    <name>{environment-name}</name>
    <tiers>
        <tier>
           <initial_number_instances>1</initial_number_instances>
           <maximum_number_instances>1</maximum_number_instances>
           <minimum_number_instances>1</minimum_number_instances>
           <name>{tier-id}</name>               
           <productReleases>                  
              <product>postgresql</product>
              <version>0.0.3</version>
              <withArtifact>true</withArtifact> 
              <productType> 
                 <id>5</id>
                 <name>Database</name>  
              </productType> 
          </productReleases>
                     ...
        </tier>   
    </tiers>
</environment>

The network and region information are including also in the payload of the enviornment. The following lines show a example.

<tier>
    <name>{tier-id}</name> 
    <region>Spain</region>
    <network>Internet</network>
    <network>private_network</network>     
    <productReleases>                  
       ...
    </productReleases>              
</tier>   

Get Environment Details

Verb URI Description
GET /paasmanager/rest/catalog/environment/{environment-id} Lists details of the specified environment.

Normal Response Code(s): 200, 203

Error Response Code(s): identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), badMediaType (415)

This operation does not require a request body and returns the details of a specific environment by its ID.

Environment Response: XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<environment>
    <name>{emvironment-name}</name>
    <tiers>
        <tier>
           <initial_number_instances>1</initial_number_instances>
           <maximum_number_instances>1</maximum_number_instances>
           <minimum_number_instances>1</minimum_number_instances>
           <name>{tier-id}</name>               
           <productReleases>                  
              <product>postgresql</product>
              <version>0.0.3</version>
              <withArtifact>true</withArtifact> 
              <productType> 
                 <id>5</id>
                 <name>Database</name>  
              </productType> 
          </productReleases>                    
        </tier>   
        <tier>
           <initial_number_instances>1</initial_number_instances>
           <maximum_number_instances>5</maximum_number_instances>
           <minimum_number_instances>1</minimum_number_instances>
           <name>{tier-id}</name>               
           <productReleases>                  
              <product>tomcat</product>
              <version>7</version>
              <withArtifact>true</withArtifact> 
              <productType> 
                 <id>6</id>
                 <name>webserver</name>  
              </productType> 
          </productReleases>   
        </tier>   
    </tiers>
</environment>

Delete Environment in the Catalogue

Verb URI Description
DELETE /paasmanager/rest/catalog/environment/{environment-id} Deletes the product with the id (environment-id) in the catalogue

Normal Response Code(s): 200, 203

Error Response Code(s): identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), badMediaType (415)

It specifies the environment ID as {environment-id} in the URI. This operation does not require a request body and returns the details of a specific environment by its ID.

Environment Provisioning

These operations involve all the operations for deploying environments in the Cloud and its management.

Deploy an environment

Verb URI Description
POST /paasmanager/rest/org/{org-id]/vdc/{vdc-id}/environmentInstance Deploy an environment including both virtual machines and required software.

Normal Response Code(s): 200 (Ok), 203 (No Service available)

Error Response Code(s): identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404)

This call deploys all the servers required (according to the Tier information) for the vdc {vdc-id}. On top of these servers, it installs the software specified.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<environment>
  <name>{emvironment-name}</name>
     <tiers>
        <tier>
           <initial_number_instances>1</initial_number_instances>
           <maximum_number_instances>1</maximum_number_instances>
           <minimum_number_instances>1</minimum_number_instances>
           <name>{tier-id}</name>               
           <productReleases>                  
              <product>postgresql</product>
              <version>0.0.3</version>
              <withArtifact>true</withArtifact> 
              <productType> 
                 <id>5</id>
                 <name>Database</name>  
              </productType> 
          </productReleases>
                   ...
       </tier>   
   </tiers>
</environment>

Environment Instance Response: XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<task href="http:/130.206.80.112:8080/paasmanager/rest/org/{org-id}/vdc/{vdc-id}/task/{task-id}" startTime="2012-11-08T09:13:18.311+01:00" status="RUNNING">
  <description>Deploy environment {emvironment-name}</description>
  <vdc>{vdc-id}</vdc>
</task>


With the URL obtained in the href in the Task, it is possible to monitor the operation status (you can check Task Management). Once the environment has been deployed, the task status should be SUCCESS.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<task href="http:/130.206.80.112:8080/paasmanager/rest/org/{org-id}/vdc/{vdc-id}/task/{task-id}" startTime="2012-11-08T09:13:19.567+01:00" status="SUCCESS">
  <description>Deploy environment {emvironment-name}</description>
  <vdc>{vdc-id}</vdc>
</task>

Get information about the environments deployed (environment instance)

Verb URI Description
GET /paasmanager/rest/org/{org-id}/vdc/{vdc-id}/environmentInstance Get information about the environments deployed

Normal Response Code(s): 200 (Ok), 203 (No Service available) Error Response Code(s): identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404)

This operation does not require a request body and returns the details of the list of environments instances deployed.


Environment Instance List Response: XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<environmentInstanceDtoes>
   <environmentInstance>
      <environmentInstanceName>{environmentInstance-id</environmentInstanceName>
      <vdc>{vdc-id}</vdc>
      <environment>
         <name>{emvironment-name}</name>
         <tiers>
            <tier>
               <initial_number_instances>1</initial_number_instances>
               <maximum_number_instances>1</maximum_number_instances>
               <minimum_number_instances>1</minimum_number_instances>
               <name>{tier-id}</name>               
               <productReleases>                  
                  <product>postgresql</product>
                  <version>0.0.3</version>
                  <withArtifact>true</withArtifact> 
                  <productType> 
                     <id>5</id>
                     <name>Database</name>  
                     </productType> 
               </productReleases>                     ...
            </tier>   
        </tiers>
      </environment>        
      <tierInstances>
         <id>35</id>
         <date>2012-10-31T09:24:45.298Z</date>  
         <name>tomcat-</name>       
         <status>INSTALLED</status>       
         <vdc>{vdc-id}</vdc>       
         <tier>
            <name>{tier-id}</name>               
         </tier>   
         <productInstances>
            <id>33</id>   
            <date>2012-10-31T09:14:33.192Z</date>  
            <name>postgresql</name>         
            <status>INSTALLED</status>    
            <vdc>{vdc-id}</vdc>  
            <productRelease>  
               <product>postgresql</product>  
               <version>0.0.3</version> 
            </productRelase>
            <vm>
               <fqn>vmfqn</fqn> 
               <hostname>rehos456544</hostname> 
               <ip>109.231.70.77</ip> 
            </vm>
         </tierInstances>
      </environmentInstance>
</environmentInstanceDtoes>

Get details about an environment deployed

Verb URI Description
GET /paasmanager/rest/org/{org-id]/vdc/{vdc-id}/environmentInstance/{environmentInstance-id} Get the details about the environments deployed

Normal Response Code(s): 200, 203

Error Response Code(s): identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), badMediaType (415)

This operation does not require any payload in the request and provides a environmentInstance XML response.


EnvironmentInstances Response: XML

<environmentInstance>
   <environmentInstanceName>{environmentInstance-id</environmentInstanceName>
   <vdc>{vdc-id}</vdc>
   <environment>
      <name>{emvironment-name}</name>
      <tiers>
         <tier>
            <initial_number_instances>1</initial_number_instances>
            <maximum_number_instances>1</maximum_number_instances>
            <minimum_number_instances>1</minimum_number_instances>
            <name>{tier-id}</name>               
            <productReleases>                  
               <product>postgresql</product>
               <version>0.0.3</version>
               <withArtifact>true</withArtifact> 
               <productType> 
                  <id>5</id>
                  <name>Database</name>  
                  </productType> 
            </productReleases>                    
                ...
         </tier>   
     </tiers>
   </environment>        
   <tierInstances>
      <id>35</id>
      <date>2012-10-31T09:24:45.298Z</date>  
      <name>tomcat-</name>       
      <status>INSTALLED</status>       
      <vdc>{vdc-id}</vdc>       
      <tier>
         <name>{tier-id}</name>               
      </tier>   
      <productInstances>
         <id>33</id>   
         <date>2012-10-31T09:14:33.192Z</date>  
         <name>postgresql</name>         
         <status>INSTALLED</status>    
         <vdc>{vdc-id}</vdc>  
         <productRelease>  
            <product>postgresql</product>  
            <version>0.0.3</version> 
         </productRelase>
        <vm>
            <fqn>vmfqn</fqn> 
            <hostname>rehos456544</hostname> 
            <ip>109.231.70.77</ip> 
         </vm>
      </productInstance>
   </tierInstances>
</environmentInstance>

Undeploy an Environment Instance

Verb URI Description
DELETE /paasmanager/rest/org/{org-id]/vdc/{vdc-id}/environmentInstance/{environmentInstance-id} Undeploy the environment deployed in the testbed (involving both servers and software)

Normal Response Code(s): 200, 203

Error Response Code(s): identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), badMediaType (415)

Specify the Environment Instance ID as {environmentInstance-id} in the URI. This operation does not require a request body and returns the details of a generated task.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<task href="http:/130.206.80.112:8080/paasmanager/rest/org/{org-id}/vdc{vdc-id}/task/{task-id}" startTime="2012-11-08T09:45:44.020+01:00" status="RUNNING">
  <description>Uninstall environment</description>
  <vdc>{vdc-id}</vdc>
</task>

With the URL obtained in the href in the Task, it is possible to monitor the operation status (you can checkTask Management). Once the environment has been undeployed, the task status should be SUCCESS.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<task href="http:/130.206.80.112:8080/paasmanager/rest/org/{org-id}/vdc/{vdc-id}/task/{task-id}" startTime="2012-11-08T09:13:19.567+01:00" status="SUCCESS">
  <description>Undeploy environment {emvironment-name}</description>
  <vdc>{vdc-id}</vdc>
</task>

Application Provisioning on top of an Environment

These operations involve all the operations for deploying applications on top of environment already deployed in the Cloud and its management.

Deploy an application

Verb URI Description
POST /paasmanager/rest/org/{org-id]/vdc/{vdc-id}/environmentInstance/{environmentInstance-id}/applicationInstance Deploy an application (together their artefacts on top of an environment already deployed)

Normal Response Code(s): 200 (Ok), 203 (No Service available)

Error Response Code(s): identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404)

This call deploys an application on top of an environment already deploying, including the deployment of all the artefacts in the associated product releases. The request involves information about the Application to be deployed mainly composed by a name, version and a set of artefacts. Current example shows the deployment of a java web application which runs on top of a Tomcat and PostgreSQL. Mainly, its instantiation involves the deployment of a war and a properties file on top of the tomcat and the execution of a .sql script in the PostgreSQL.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<applicationReleaseDto>
  <applicationName>{application-name}</applicationName>
  <version>{application-version}</version>
  <artifacts>
     <artifact>
        <name>thewarfile</name>
        <attributes>
           <key>webapps_url</key><value>http://Artefacts/WAR/tomcatFixedLocalPostgresDB/flipper.war</value>
           <key>webapps_name</key><value>flipper.war</value>
        </attributes>
        <productRelease>
           <version>7.0</version>
           <product>tomcat</product>
        </productRelease> 
     </artifact>
     <artifact>
        <name>the properties file</name>
        <attributes>
           <key>properties_url</key><value>http://configuration.prperties</value>
           <key>properties_name</key><value>flipper.war</value>
        </attributes>
        <productRelease>
           <version>7.0</version>
           <product>tomcat</product>
        </productRelease> 
     </artifact>
     <artifact>
        <name>a .sql script</name>
        <attributes>
           <key>sql_script_url</key><value>http://script.sql</value>
        </attributes>
        <productRelease>
           <version>1.2</version>
           <product>postgreSQL</product>
        </productRelease> 
     </artifact>
  </artifacts>
<applicationReleaseDto>

The result for provisioning the application is a Task indicating the operation status:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<task href="http:/130.206.80.112:8080/paasmanager/rest/org/{org-id}/vdc/{vdc-id}/task/{task-id}" startTime="2012-11-08T09:13:18.311+01:00" status="RUNNING">
  <description>Deploy application {application-name}</description>
  <vdc>{vdc-id}</vdc>
</task>


With the URL obtained in the href in the Task, it is possible to monitor the operation status. Once the application has been deployed, the task status should be SUCCESS.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<task href="http:/130.206.80.112:8080/paasmanager/rest/org/{org-id}/vdc/{vdc-id}/task/{task-id}" startTime="2012-11-08T09:13:19.567+01:00" status="SUCCESS">
  <description>Deploy application {application-name}</description>
  <vdc>{vdc-id}</vdc>
</task>

Get information about the applications already deployed in a environment (application instance)

Verb URI Description
GET /paasmanager/rest/org/{org-id]/vdc/{vdc-id}/environmentInstance/{environmentInstance-id}/applicationInstance Get information about the applications deployed in the environment

Normal Response Code(s): 200 (Ok), 203 (No Service available) Error Response Code(s): identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), itemNotFound (404)

This operation does not require a request body and returns the details of the list of application instances deployed.

Application Instance List Response: XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<applicationInstanceDtoes>
   <applicationInstance>
      <id>206</id>
      <date>2012-12-03T08:42:21.294+01:00</date>
      <name>{application-name}</name>
      <status>APPLICATION_INSTALLED</status>
      <vdc>{vdc_id}</vdc>    
      <applicationRelease>       
         <name>{application-name}</name>
         <version>{application-version}</version>
         <artifacts>
            <artifact>
               <name>thewarfile</name>
               <attributes>
                  <key>webapps_url</key><value>http://Artefacts/WAR/tomcatFixedLocalPostgresDB/flipper.war</value>
                  <key>webapps_name</key><value>flipper.war</value>
               </attributes>
               <productRelease>
                  <version>7.0</version>
                  <product>tomcat</product>
               </productRelease> 
            </artifact>
            <artifact>
               <name>the properties file</name>
               <attributes>
                  <key>properties_url</key><value>http://configuration.prperties</value>
                  <key>properties_name</key><value>flipper.war</value>
               </attributes>
               <productRelease>
                  <version>7.0</version>
                  <product>tomcat</product>
               </productRelease> 
            </artifact>
            <artifact>
               <name>a .sql script</name>
               <attributes>
                  <key>sql_script_url</key><value>http://script.sql</value>
               </attributes>
               <productRelease>
                  <version>1.2</version>
                  <product>postgreSQL</product>
               </productRelease> 
            </artifact>
         </artifacts>
      </applicationRelease>
      <environmentInstance>
         <id>202</id>
         <date>2012-11-30T13:40:55.941+01:00</date>
         <name>environmetntomcat</name>
         <status>INSTALLED</status>
         <vdc>{vdc-id}</vdc>
         <environment>
            <name>{environment_name}</name>
            <tiers>
               <name>tomcat</name>
                     ...       
         </environment>
         <tierInstances>
            <id>201</id>
            <date>2012-11-30T13:40:55.941+01:00</date>
            <status>INSTALLED</status>
            <tier>
               <name>tomcat</name>
               <productReleases>
                  <product>tomcat</product>
                  <version>7.0</version>
               </productReleases>          
            </tier>
            <fqn>{environment_name}_tomcat fqn</fqn>
            <name>{environment_name}_tomcat</name>
            <productInstances>
               <id>200</id>
               <date>2012-11-30T13:40:50.786+01:00</date>
               <status>ARTEFACT_DEPLOYED</status>
               <productRelease>
                  <product>tomcat</product>
                  <version>7.0</version>
               </productRelease> 
               <vm>
                  <fqn>4caast.customers.test4.services.testtomcatsap16.vees.tomcat.replicas.1</fqn>
                  <hostname>relhot2345</hostname>
                  <ip>130.206.80.114</ip>
               </vm>
            </productInstances>
         </tierInstances>
      </environmentInstance>
   </applicationInstance>
</applicationInstanceDtoes>

Get details about an application already deployed

Verb URI Description
GET /paasmanager/rest/org/{org-id]/vdc/{vdc-id}/environmentInstance/{environmentinstance-id}/applicationInstance/{applicationInstance-id} Get the details about the application deployed

Normal Response Code(s): 200, 203

Error Response Code(s): identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), badMediaType (415)

This operation does not require any payload in the request and provides an applicationInstance XML response.

ApplicationInstance Response: XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<applicationInstance>
   <id>206</id>
   <date>2012-12-03T08:42:21.294+01:00</date>
   <name>{application-name}</name>
   <status>APPLICATION_INSTALLED</status>
   <vdc>{vdc_id}</vdc>    
      <applicationRelease>       
         <name>{application-name}</name>
         <version>{application-version}</version>
         <artifacts>
            <artifact>
               <name>thewarfile</name>
               <attributes>
                  <key>webapps_url</key><value>http://Artefacts/WAR/tomcatFixedLocalPostgresDB/flipper.war</value>
                  <key>webapps_name</key><value>flipper.war</value>
               </attributes>
               <productRelease>
                  <version>7.0</version>
                  <product>tomcat</product>
               </productRelease> 
            </artifact>
            <artifact>
               <name>the properties file</name>
               <attributes>
                  <key>properties_url</key><value>http://configuration.prperties</value>
                  <key>properties_name</key><value>flipper.war</value>
               </attributes>
               <productRelease>
                  <version>7.0</version>
                  <product>tomcat</product>
               </productRelease> 
            </artifact>
            <artifact>
               <name>a .sql script</name>
               <attributes>
                  <key>sql_script_url</key><value>http://script.sql</value>
               </attributes>
               <productRelease>
                  <version>1.2</version>
                  <product>postgreSQL</product>
               </productRelease> 
            </artifact>
         </artifacts>
      </applicationRelease>
      <environmentInstance>
         <id>202</id>
         <date>2012-11-30T13:40:55.941+01:00</date>
         <name>environmetntomcat</name>
         <status>INSTALLED</status>
         <vdc>{vdc-id}</vdc>
         <environment>
            <name>{environment_name}</name>
            <tiers>
               <name>tomcat</name>
                     ...       
         </environment>
         <tierInstances>
            <id>201</id>
            <date>2012-11-30T13:40:55.941+01:00</date>
            <status>INSTALLED</status>
            <tier>
               <name>tomcat</name>
               <productReleases>
                  <product>tomcat</product>
                  <version>7.0</version>
               </productReleases>          
            </tier>
            <fqn>{environment_name}_tomcat fqn</fqn>
            <name>{environment_name}_tomcat</name>
            <productInstances>
               <id>200</id>
               <date>2012-11-30T13:40:50.786+01:00</date>
               <status>ARTEFACT_DEPLOYED</status>
               <productRelease>
                  <product>tomcat</product>
                  <version>7.0</version>
               </productRelease> 
               <vm>
                  <fqn>4caast.customers.test4.services.testtomcatsap16.vees.tomcat.replicas.1</fqn>
                  <hostname>relhot2345</hostname>
                  <ip>130.206.80.114</ip>
               </vm>
            </productInstances>
      </tierInstances>
   </environmentInstance>
</applicationInstance>

Undeploy an Application Instance

Verb URI Description
DELETE /paasmanager/rest/org/{org-id]/vdc/{vdc-id}/environmentInstance/{environmentinstance-id}/applicationInstance/{applicationInstance-id} Undeploy the application deployed in the environment instance

Normal Response Code(s): 200, 203

Error Response Code(s): identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), badMediaType (415)

It specifies the Environment Instance ID as {environmentInstance-id} and the application instance ID as {applicationInstance-id} in the URI. This operation does not require a request body and returns the details of a generated task.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<task href="http:/130.206.80.112:8080/paasmanager/rest/org/{org-id}/vdc{vdc-id}/task/{task-id}" startTime="2012-11-08T09:45:44.020+01:00" status="RUNNING">
  <description>Uninstall application</description>
  <vdc>{vdc-id}</vdc>
</task>

With the URL obtained in the href in the Task, it is possible to monitor the operation status (you can check Task Management). Once the environment has been deployed, the task status should be SUCCESS.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<task href="http:/130.206.80.112:8080/paasmanager/rest/org/{org-id}/vdc/{vdc-id}/task/{task-id}" startTime="2012-11-08T09:46:44.020+01:00" status="SUCCESS">
  <description>Uninstall application</description>
  <vdc>{vdc-id}</vdc>
</task>

Task Management

Verb URI Description
GET /rest/vdc/{vdc-id}/task/{task-id} Get the status of a task.

Normal Response Code(s): 200, 203

Error Response Code(s): identityFault (400, 500, …), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), serviceUnavailable (503), badMediaType (415)

This operation recovers the status of a task created previously. It does not need any request body and the response body in XML would be the following.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<task href="http:/130.206.80.112:8080/sdc/rest/vdc/{vdc-id}/task/{task-id}" startTime="2012-11-08T09:13:18.311+01:00" status="SUCCESS">
  <description>Install product tomcat in  VM rhel-5200ee66c6</description>
  <vdc>{vdc-id}</vdc>
</task>

The value of the status attribute could be one of the following:

Value Description
QUEUED The task is queued for execution.
PENDING The task is pending for approval.
RUNNING The task is currently running.
SUCCESS The task is completed successfully.
ERROR The task is finished but it failed.
CANCELLED The task has been cancelled by user.
Personal tools
Create a book