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
SDC Open RESTful API Specification - FIWARE Forge Wiki

SDC Open RESTful API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the Software Deployment and Configuration (SDC) API

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

SDC API Core

The Software Deployment and Configuration (SDC) 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 SDC offers some mechanisms to install, uninstall, and configure products and applications in a running operating system.

Intended Audience

This specification is intended for both software developers and final users. For the former, this document provides a full specification of how to include new software in the catalogue of the SDC. For the latter, this specification indicates the interface to be provided in order to clients to manage software in their virtual machines. To use this information, the reader should firstly have a general understanding of the SDC Generic Enabler and also be familiar with:

  • RESTful web services
  • HTTP/1.1 (RFC2616)
  • JSON and/or XML data serialization formats.

API Change History

This is the first version for the SDC API

Version Changes Summary
Oct 09, 2012
  • First version of the SDC API, API uses for managing software on top of server.


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 SDC that this API is based upon, please refer to FI-WARE Cloud Hosting.

General SDC API Information

Resources Summary

Graphical diagram in which the different URNs that can be used in the API is shown here. The PaaS Manager API can start with http://SDC_IP:port/sdc/rest

SDC API resources


SDC Open RESTful API resource summary

Authentication

There is not yet

Representation Format

The SDC 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/product HTTP/1.1
Host: sdc.paas.tid.org
Content-Type: application/json
Accept: application/xml
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb


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


POST /catalog/product HTTP/1.1
Host: sdc.paas.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. SDC 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.

SDC API does not enforce any determined URL pattern to identify its resources. Anyway the SM Extension 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.

SDC 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. 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.

SDC 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
badMethod 405 Method not allowed
overLimit 413 Request entity too large


Besides the previous errors, when there is a error in the SDC operation, the SDC prints 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.

<task href="http://130.206.80.112:8080/sdc/rest/vdc/{vdc-id}/task/81" startTime="2012-11-19T08:20:24.844+01:00" endTime="2012-11-19T08:20:50.700+01:00" status="ERROR">
  <error message="The product tomcat-7 can not be installed in server since the server does not exists"  minorErrorCode="SdcRuntimeException"/>
  <result href="http://130.206.80.112:8080/sdc/rest/vdc/{vdc-id}/product/82"/>
  <description>Install product tomcat in server</description>
  <vdc>{vdc-id}</vdc>
</task>

In this case the main controlled exceptions are:

  1. ProductNotFoundException: The product not exist in the catalogue
  2. ProductInstanceNotFoundException: The product instance has not been deployed in the server
  3. ProductReleaseNotFoundException: The product release in not stored in the catalogue
  4. InvalidInstallProductRequestException: The product to be installed in the server is not valid
  5. InvalidProductReleaseException: The product release to be introduced in the catalogue is not valid
  6. IncompatibleProductsException: The products to be installed are incomptibles
  7. AlreadyExistsProductReleaseException: The product release ist already in the catalogue
  8. AlreadyInstalledException: The product is already deployed in the server
  9. NotInstalledProductsException: The product to be undeployed in the not installed in the server
  10. InvalidProductReleaseUpdateRequestException: The product cannot be updated
  11. CanNotDeployException: It is not possible to do any action in the server (install, uninstall and so no).
  12. CanNotCallChefException: It is not possible to call the Chef server to execute any action.
  13. NodeExecutionException: There is an error in the execution of chef in the node
  14. FSMViolationException: It is not possible to execute an action to the node. The node is not in the right status
  15. ShellCommandException: There is an error in executing a command in the node
  16. SdcRuntimeException: An internal SDC error has happened.

API Operations

In this section we go in depth for each operation. These operations have been described in theSDC Architecture. The FIWARE programmer guide will also provide examples of how to use the API. The SDC API is divided among two funciotnalities: the catalogue of the software to be deployed and the provisioning of this software. Due to it, we make two main divisions in the API explanation. All the payload examples in this section are formalized in XML, but the user could use also JSON as representation format.

Product Catalogue

List Products in the catalogue

Verb URI Description
GET /sdc/rest/catalog/product Lists all Product 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 products stored in the catalogue.

The following example shows an XML response for the list Product API operation:

<?xml version="1.0" encoding="UTF-8"?>
<products>
   <product>
      <name>tomcat</name>
      <description>tomcat J2EE container</description>
      <attributes>
         <key>port</key>
         <value>8080</value>
         <description>The listen port</description>
      </attributes>
      <attributes>
         <key>ssl_port</key>
         <value>8443</value>
         <description>The ssl listen port</description>
      </attributes>
   </product>
</product>


Add a product to the catalogue

Verb URI Description
POST /sdc/rest/catalog/product Add the selected Product Release into the SDC's catalog. If the Product already exists, then add the new Release. If not, this method also creates the product.

Normal Response Code(s): 200

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 product in the catalogue. This call creates a new Product in the catalogue.

<?xml version="1.0" encoding="UTF-8"?>
<product>
  <name>postgresql</name>
  <description>db manager</description>
  <attributes>
    <key>username</key>
    <value>postgres</value>
    <description>The administrator usename</description>
  </attributes>
  <attributes>
    <key>password</key>
    <value>postgres</value>
    <description>The administrator password</description>
  </attributes>
</product>


Get Product Details

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

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 Product ID as productId in the URI. This operation does not require a request body and returns the details of a specific product by its ID.

Product Response: XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<product>
   <name>tomcat</name>
   <description>tomcat J2EE container</description>
   <attributes>
      <key>port</key>
      <value>8080</value>
      <description>The listen port</description>
   </attributes>
   <attributes>
     <key>ssl_port</key>
     <value>8443</value>
     <description>The ssl listen port</description>
   </attributes>
</product>


Delete Product in the Catalogue

Verb URI Description
DELETE /sdc/rest/catalog/product/{product-id} Deletes the product with the id (product-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 ID of the product in the URI. This operation does not require a request body and returns without any body.


Get Product Attributes

Verb URI Description
GET /sdc/rest/catalog/product/{product-id}/attributes Get the attributes fot the product.

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 ID of the product in the URI. This operation does not require a request body and returns the details of a specific product by its ID.

Attributes XML:

<attributes>
  <attribute>
    <key>port</key>
    <value>8080</value>
    <description>The listen port</description>
  </attribute>
  <attribute>
    <key>ssl_port</key>
    <value>8443</value>
    <description>The ssl listen port</description>
  </attribute>
</attributes>


Product Provisioning

Install a product

Verb URI Description
POST /sdc/rest/vdc/{vdc-id}/productInstance Install a product in a server

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 call deploys a Product (existing in the catalogue) in a server for the vdc {vdc-id}. It request provides server features like IP are in the payload as well as the product characteristics to be installed.

<?xml version="1.0" encoding="UTF-8"?>
<productInstanceDto>
  <vm>
    <ip>130.206.80.114</ip>
    <fqn>fqnname</fqn>
    <osType>95</osType>
    <hostname>rhel-5200ee66c6</hostname>
  </vm>
  <product>
    <productDescription/>
    <productName>tomcat</productName>
    <version>7</version>
    <supportedOOSS>
        <osType>Debian 5</osType>
        <name>Debian 5</name>
        <version>5</version>
      </supportedOOSS>
 </product>
</productInstanceDto>

Once executed the request, the SDC returns a Task to manage this operation. This task specifies the status of the operation, a description and more information. Thus, in this case the product provisioning Response is a XML like that

<?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="RUNNING">
  <description>Install product tomcat in  VM rhel-5200ee66c6</description>
  <vdc>{vdc-id}</vdc>
</task>

Then, when the product has been installed asking for the task status

  GET http:/130.206.80.112:8080/sdc/rest/vdc/{vdc-id}/task/{task-id}

It is possible to obtain, the sucess status.

<?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>

Get information about the products installed (product instances) in a server

Verb URI Description
GET /sdc/rest/vdc/{vdc-id}/productInstance Install a product in a server

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 and returns the details of the list of product instances deployed in the server.

Product Instance List Response: XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<productInstances> 
  <productInstance>
    <id>56</id>
    <date>2012-11-07T15:56:30.590+01:00</date>
    <status>INSTALLED</status>
    <vm> 
      <ip>130.206.80.114</ip>
      <hostname>rhel-5200ee66c6</hostname>
      <fqn>fqn</fqn>
      <osType>95</osType>
    </vm>
    <vdc>{vdc-id}</vdc>
    <product>
      <releaseNotes>Tomcat server 7</releaseNotes>
      <version>7</version>
      <product>
        <name>tomcat</name>
        <description>tomcat J2EE container</description>
        <attributes>
           <key>port</key>
           <value>8080</value>               
        </attributes>                
      </product>           
   </product>
  </productInstance>
</productInstances> 


Get details about a product installed in a server

Verb URI Description
GET /sdc/rest/vdc/{vdc-id}/productInstance/{productInstance-id} Lists of Products installed in the server

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 productInstances XML response.

Product Instances Response: XML

<productInstance>
   <id>{productInstance-id}</id>
   <date>2012-11-08T15:30:56.764+01:00</date>
   <status>INSTALLED</status>
   <vm>           
      <ip>130.206.80.114</ip>   
      <hostname>testchef</hostname>   
      <domain>.test</domain>        
      <fqn>es.tid.dd</fqn>                 
   </vm> 
   <vdc>{vdc-id}</vdc>    
   <product>
      <name>tomcat</name>
      <description>tomcat J2EE container</description>
      <attributes>
         <key>port</key>
         <value>8080</value>
         <description>The listen port</description>
      </attributes>
      <attributes>
         <key>ssl_port</key>
         <value>8443</value>
         <description>The ssl listen port</description>
      </attributes>
   </product>
</productInstance>


Uninstall product in the server

Verb URI Description
DELETE /sdc/rest/vdc/{vdc-id}/productInstance/{productInstance-id} Uninstall the product belonging the the product instance {productInstanceId} in the server.

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 is required to specify the Product Instance to be undeployed. 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/sdc/rest/vdc/{vdc-id}/task/72" startTime="2012-11-08T09:45:44.020+01:00" status="RUNNING">
  <description>Uninstall product tomcat in  VM rhel-5200ee66c6.</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