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
Cloud Edge Service Management API Specification - FIWARE Forge Wiki

Cloud Edge Service Management API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction

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

Service Platform Management API Core

The Service Platform API allows managing Virtual Applications running on the cloud Edge. This is a RESTful, resource-oriented API accessed via HTTP that uses JSON-based representations for information interchange.

This API provides all the necessary methods to enable management of both the catalogue of Services (called Images) available on the platform and the Instances (Virtual Application) that can be installed on the device.

Intended Audience

This specification is intended for Software Developers, Cloud Operators and Reimplementers.

  • For the Software Developpers and Reimplementers, this document provides a full specification of how to interoperate with Cloud Edge Platforms that implement the Service Platform Management API.
  • For the Cloud Operators, this specification indicates the interface to be provided in order for clients to interoperate with Cloud Edge Platform to provide the described functionalities. To use this information, the reader should firstly have a general understanding of the Generic Enabler service Cloud Edge General Description.

API Change History

Revision Date Changes Summary
March 31st, 2012 1st version, XML-RPC compatible (limited availability)
April 30th, 2012 RESTFull API, subset of the functionalities; UBUNTU platform (v1.0)
March 12th, 2013 embedded platform (v2.2)
June 14th, 2013 added "reset" in "action on platform" (v2.3)

How to Read This Document

All FI-WARE RESTful API specifications will follow the same list of conventions and will support certain common aspects. Please check Common aspects in FI-WARE Open Restful API Specifications.

For a description of some terms used along this document, see Cloud Edge General Description.

Additional Resources

You can download the most current version of this document from the FIWARE API specification website at [1]. For more details about the Cloud Edge Service that this API is based upon, please refer to Cloud Hosting. Related documents, including an Architectural Description, are available at the same site.

General Service Platform Management API Information

Resources Summary

  • The Cloud Proxy Management API exposes a set of commands on the Cloud Proxy GE that enables the management of the virtual appliances. This is done through manipulating different objects, like:
  • images: represent Services that could be installed on the Cloud Edge
  • instances: represent the Virtual Applications that could run on the Cloud Edge
  • users: represent actors that are registered in the Cloud Proxy and that are allowed to interact with Cloud Edge Management Platform.
  • platform: regroup the info that describes the Cloud Edge.
  • forwarding rules: represent some forwarding rules that needs to be apply on the Cloud Edge to manage the reachability of the Virtual Appliance.

Authentication

Each Http request against the Service Platform Manager of the Cloud Edge requires the inclusion of specific authentication credentials. This is achieved by using Http Basic Authentication scheme.

Representation Format

The Service Platform Management API supports JSON-based representation.

Representation Transport

The resource representation is transmitted between client and server by using HTTPS protocol . Each message is based on HTTP 1.1 requests carried on top of a SSL connection. The header of each message contains a specified User-agent, a specified Host, a Content-Type header set as “application/json” and a Content-Length set to correct length of the message.

Example of a typical Header Message of standard request:

GET /cloudedge/version HTTP/1.1
Authorization: Basic c21pdGhqOnNlY3JldA==
User-Agent: curl/7.22.0 libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
Host: myserver.example.com:8080
Accept: application/json
Content-type: application/json

Resource Identification

The resource identification used by this API is based on the URI scheme described by HTTP protocol specification as defined by IETF RFC-2616 ( https://www.ietf.org/rfc/rfc2616.txt )

Links and References

Some responses may contais reference to other resources managed by the Cloud Edge. Those links are represented as a standard URL tagged with the word “link” (see example below)

Example of links provided in an operation response:

{
 "instances": [
   {
     "id": 237,
     "image": {
       "id": 61,
       "name": "test",
       "link": "https://myhome.example.com/cloudedge/images/61"
     },
     "link": "https:// myhome.example.com /cloudedge/instances/237"
   }
 ]
}

Versions

The API version that is currently running on cloud proxy is accessible by issuing a an HTTP get request on the following URI : /cloudege/platform/version (for details refer to the description in API Operation chapter). API versions follow a simple pattern: x.y with y being a minor version mainly for internal purpose and x a ‘major’ version which indicates a major change in the API (such as signature change or other incompatibility).

Faults

Here are the faults that a Cloud Proxy service can return:

Fault Element Associated Error Codes
computeFault 500, 400
serviceUnavailable 503
unauthorized 401
forbidden 403
badRequest 400
overLimit 413
badMediaType 415
badMethod 405
itemNotFound 404
buildInProgress 409
serverCapacityUnavailable 503
backupOrResizeInProgress 409
resizeNotAllowed 403
notImplemented 501

API Operations

In this section we go in depth for each operation. In order to provide comprehensive view of the API operations, the functionalities are organized per group of functionalities.

Platform Functionalities

Get Platform Resources

Verb URI Description
GET /cloudedge/platform List the capabilities, versions and resources available on the platform

Normal Response Code: 200

Error Response Code(s): computeFault (400, 500, …), unauthorized (401), forbidden (403), badRequest (400), badMethod (405) This operation does not require a request body

Here is the list of typical information that is detailed in the response body:

Type SubType Description
name Provides the name of the platform
version major Retrieve the full version information about the running Cloud Edge Service software.
minor
cpu Provides the type of CPU that is running in the platform
ram Amount of installed memory (in Megabytes)
disk Amount of installed disk space (in Megabytes)
metrics cpuUsage Current CPU usage (%)
ramUsage Current RAM usage (Megabytes)
diskUsage Current disk usage (Megabytes)
networkIn total received data from poweron (bytes)
networkOut total transmitted data from poweron (bytes)

Example: get platform resources Response:

{
 "platform": {
  "name" : "Dti716"
  "version" : {
   "major" : 1,
   "minor" : 3
  }
  "ressources" : {
   "cpu": "i686"
   "ram" : 512,
   "disk" : 4096
  }
  "metrics" : {
   "cpuUsage" : 38,
   "ramUsage" : 384,
   "diskUsage" : 2048,
   "networkIn" : 65786578,
   "networkOut" : 8689756
  }
}

Images

List Images

Verb URI Description
GET /cloudedge/images Return the list of all image (IDs, names, links) available in the Cloud Proxy associated to the User account.

Normal Response Code: 200

Error Response Code(s): computeFault (400, 500, …), unauthorized (401), forbidden (403), badRequest (400), badMethod (405)

Example: List Instances Response:


{
 "images": [
   {
     "id": 278,
     "name": "fliker++",
     "link": "https://cloudedge.myhome.net/cloudedge/images/278"
   },
   {
     "id": 45,
     "name": "osgi",
     "link": "https://cloudedge.myhome.net/cloudedge/images/45"
   }
 ]
}

Get Images Details

Verb URI Description
GET /cloudedge/images/id Returns details on the specified ("id") image.

Normal Response Code(s): 200


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


Specify the server ID as id in the URI.


This operation does not require a request body.

This operation returns the details of a specific server by its ID.

Example: Get image detail Response:

{
 "image": {
     "id": 237,
     "name": "test",
     "uuid": "7feb24af-fc38-44de-bc38-04defc3804de",
     "description": "test server",
     "status": "ACTIVE",
     "created_by": 78945
     "created_at": "2012-06-25T15:23:33+02:00",
     "link": "https://cloudedge.myhome.net/cloudedge/images/237"
   }
}

Create Image

Verb URI Description
POST /cloudedge/images Registers a specified image into the system.

Normal Response Code: 202

Error Response Code(s): computeFault (400, 500, …), unauthorized (401), forbidden (403), badRequest (400), badMethod (405), itemNotFound (404)


This operation registers an image into the cloud proxy. This operation makes this Service available on the local catalogue and being ready to be installed. The following table describes the required and optional attributes that you can specify in the request body:

Name Description Required
imageRef The image reference for the desired image (specify a full URL) yes
name The image name. Choose any name you want yes


Example: Register image Request

{
 "image":
   {
     "name": "test",
     "imageRef": “http://www.example.com/images/test.tar”,
   }
}


Example: Register image Response

{
 "image": {
     "id": 237,
     "name": "test",
     "link": "https://cloudedge.myhome.net/cloudedge/images/237"
   }
}


The Cloud Edge Virtual Machine image is composed of:

  • A manifest file
  • A rootFS image

Example of manifest file: <- in "test.tar" in the previous example

<?xml version="1.0" encoding="utf-8"?>
<manifest
 uuid="7feb24af-fc38-44de-bc38-04defc3804de"
 label="test"
 description="test server"
 rootfs="rootfs-openssh.tar.gz">     <- this is the rootFS file name
</manifest>

Delete Image

Verb URI Description
DELETE /cloudedge/images/id Deletes the {id} image.


Normal Response Code: 204

Error Response Code(s): computeFault (400, 500, ...), serviceUnavailable (503),

unauthorized (401), forbidden (403), badRequest (400), badMethod (405), itemNotFound (404), buildInProgress (409)


This operation deletes the specified image from the system.

Specify the image ID as id in the URI.

Images are immediately removed.

This operation does not require a request body or return a response body.

Instances

List Instances

Verb URI Description
GET /cloudedge/instances?image=imageid List IDs, names and links for all Instances associated to the User credential.

Normal Response Code(s): 200

Error Response Code(s): computeFault (400, 500, ...), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405)

If additional query parameter is provided in the URI, then select only the subset of those instances that match the defined criteria. Currently, only a filter based on image is implemented; this filter is expecting a valid image Id.

Example: List Instances Response:


{
 "instances": [
   {
     "id": 237,
     "name": "test-instance-237",
     "link": "https://cloudedge.myhome.net/cloudedge/instances/237"
   },
   {
     "id": 238,
     "name": "osgi-instance-238",
     "link": "https://cloudedge.myhome.net/cloudedge/instances/238"
   }
 ]
}

Get Instance Details

Verb URI Description
GET /cloudedge/instances/id Get details on the {id} instance.

Normal Response Code(s): 200


Error Response Code(s): computeFault (400, 500, ...), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405), itemNotFound (404)


Specify the server ID as id in the URI.

This operation does not require a request body.


Example: Instance Details Response:

{
 "instance":  {
     "id": 237,
     "name": "test-instance-237",
     "status": "running",
     "metrics" : {
      "cpuUsage" : 12,
      "ramUsage" : 28,
      "diskUsage" : 35,
      "networkIn" : 157865,
      "networkOut" : 589756
     }
     "image": {
       "id": 61,
       "name": "test",
       "link": "https://cloudedge.myhome.net/cloudedge/images/61"
     },
     "created_by": "smithj",
     "ip": "10.0.3.2",
     "created_at": "2012-06-25T15:23:33+02:00",
     "link": "https://cloudedge.myhome.net/cloudedge/instances/237"
   }

}

Action On Instance

Verb URI Description
POST /cloudedge/instances/id/action Do action (start, stop, reboot, pause, resume) on the {id} instance.

Normal Response Code(s): 202

Error Response Code(s): computeFault (400, 500, ...), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405), itemNotFound (404), badMediaType (415), buildInProgress (409)

In the Request body specify the type of action you want to do followed by attributes (if needed)


This operation does not return a response body.

Example: Action Start request:

{
           “start” : null
}


Example: Action Stop request:

{         
           “stop” : null
}

Action On Platform

Verb URI Description
POST /cloudedge/platform/action do action on platform (reboot or reset).

Normal Response Code(s): 202

Error Response Code(s): computeFault (400, 500, ...), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405), itemNotFound (404), badMediaType (415), buildInProgress (409)

In the Request body specify the type of action you want to do followed by attributes (if needed)

Specific attributes: none


This operation does not return a response body.

Example: reboot request:

{
           "reboot" : null
}

Example: reset request:

{
           "reset" : null
}

note: reset deletes the installed VMs and is mostly intended to be used during debug phases while reboot simply restarts the system (keeping the VMs).

Create an Instance

Verb URI Description
POST /cloudedge/instances Create an instance.

Normal Response Code(s): 202 Error Response Code(s): computeFault (400, 500, ...), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405), itemNotFound (404), badMediaType (415)


To create a new instance, the only required attribute that need to be specified is the imageRef. This imageRef represent the image {id} from which the instance is created.

Example: Instance Create Request:

{
           "instance" : {
                       "imageRef" : 62
           }
}


Example: Instance Create Response:

{
 "instance": {
     "id": 238,
     "name": "osgi-instance-238",
     "status": "stopped",
     "image": {
       "id": 62,
       "name": "osgi",
       "link": "https://cloudedge.myhome.net/cloudedge/instances/images/62"
     },
     "ip": "10.0.3.3",
     "created_at": "2012-09-14T18:13:22+02:00",
     "link": "https://cloudedge.myhome.net/cloudedge/instances"
   }
}

Delete an Instance

Verb URI Description
DELETE /cloudedge/instances/id Deletes the specified {id} instance.

Normal Response Code: 204

Error Response Code(s): computeFault (400, 500, ...), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405), itemNotFound (404), buildInProgress (409)


This operation deletes the specified instance from the system.

Specify the instance ID as id in the URI.

Instances are immediately removed.

This operation does not require a request body or return a response body.

Forwarding rules

List forwarding rules

Verb URI Description
GET /cloudedge/fwrules?instance=instanceId Retrieve the list of Port forwarding rules. If instance_id specified then provide only the rules attached to an instance .

Normal Response Code(s): 200

Error Response Code(s): computeFault (400, 500, ...), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405)

If additional query parameter is provided in the URI, then select only the subset of those instances that match the defined criteria. Currently, only a filter based on instance is implemented. This filter is expecting a valid instance Id.

Example: List fwrules Response:

{
 "fwrules": [
   {
     "id": 237,
     "instance_id": 54,
     "link": "https://cloudedge.myhome.net/cloudedge/fwrules/237"
   },
   {
     "id": 238,
     "instance_id": 59,
     "link": "https://cloudedge.myhome.net/cloudedge/fwrules/278"
   }
 ]
}

Get Forwarding Rules Details

Verb URI Description
GET /cloudedge/fwrules/id Get details of the forwarding rule {id].

Normal Response Code(s): 200

Error Response Code(s): computeFault (400, 500, ...), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405), itemNotFound (404)

Specify the forwarding rule ID as id in the URI.

This operation does not require a request body.

Example: Forwarding rule Details Response:

{
 "fwrule":    {
     "id": 237,
     "port_to": 22,
     "port_from": 7022,
     "instance": {
       "id": 61,
       "name": "test",
       "link": "https://cloudedge.myhome.net/cloudedge/intances/61"
     },
     "created_at": "2012-06-25T15:23:33+02:00",
     "updated_at": "2012-09-12T17:16:38+02:00",
     "link": "https://cloudedge.myhome.net/cloudedge/fwrules/237"
   }
}

Create a Forwarding Rule

Verb URI Description
POST /cloudedge/fwrules Creates a forwarding rule.

Normal Response Code(s): 202

Error Response Code(s): computeFault (400, 500, ...), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405), itemNotFound (404), badMediaType (415)/


The following list describes the required attributes that you can specify in

the request body:

Name Description
instanceRef The instance reference for the desired image for your server instance. Specify as an ID. To get a list of available instances, see “List Instances”
port_to the public port on the instance where the traffic should be sent.

Example: Forwarding rule Create Request:

{
 "fwrule":    {       
       "instanceRef": 238,
       "port_to": 22,
 }
}

Example: Forwarding rule Create Response:

{
 "fwrule":    {
     "id": 77,
     "port_to": 22,
     "port_from": 7020,
 }
}


Delete a Forwarding Rule

Verb URI Description
DELETE /cloudedge/fwrules/id Deletes the {id} forwarding rule.

Normal Response Code: 204

Error Response Code(s): computeFault (400, 500, ...), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405), itemNotFound (404)

This operation deletes forwarding rule from the system.

Specify the forwarding rule ID as id in the URI.

Forwarding rule are immediately deleted from the system.

This operation does not require a request body or return a response body.

Users

List Users

Verb URI Description
GET /cloudedge/users?role=rolename Retrieve the list user registered on the system.

Normal Response Code(s): 200

Error Response Code(s): computeFault (400, 500, ...), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405)

If a "role" query parameter is provided in the URI, then this select only the subset of those users that match the defined criteria. This filter is expecting a valid role, either

  • "admin": basically get all the rights
  • "provider": remote agent that is allowed to get a full visibility on the platform, manage images proposed on the platform. These type of users are exclusively administered by the “admin” agent.
  • "guest": local agent that can install any instances from the local catalogue and manage them (start, stop, delete).
  • "local_admin": local agent that have the full control of all appliances running on the system. This agent can also administer “guest” users (create or delete guest accounts)

Example: List Users Response:

{
 "Users": [
   {
     "id": 237,
     "name": "root",
     "role": "admin",
     "link": "https://cloudedge.myhome.net/cloudedge/users/237"
   },
   {
     "id": 242,
     "name": "smithj",
     "role": "user",
     "link": "https://cloudedge.myhome.net/cloudedge/users/242"
   },
   {
     "id": 253,
     "name": "telecom",
     "role": " provider",
     "link": "https://cloudedge.myhome.net/cloudedge/users/253"
   }
 ]
}

Get User Detail

Verb URI Description
GET /cloudedge/users/id Retrieve the account details for the {id} user.

Normal Response Code(s): 200

Error Response Code(s): computeFault (400, 500, ...), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405)

Example: Get User detail Response:

{
 "User": {
     "id": 237,
     "name": "root",
     "role": "admin",
     "email": "jsmith@www.example.com"
     "created_at": "2012-05-00T15:23:00+02:00",
     "updated_at": "2012-07-12T17:10:38+02:00",
     "link": "https://cloudedge.myhome.net/cloudedge/users/237"
   }
}

Create an User

Verb URI Description
POST /cloudedge/users Create an user.

Normal Response Code(s): 202

Error Response Code(s): computeFault (400, 500, ...), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405), itemNotFound (404), badMediaType (415)

The following table describes the required and optional attributes that you can specify in the request body:

Name Description Required?
username The username or unique id used to login on the API server yes
role The role specified for the desired image for this user yes
email email @ to be used if the password needs to be reset no


Example: Create User Request:

{
 "User": {
     "username": " jsmith ",
     "role": "admin",
     "email": "jsmith@www.example.com"
   },
}

Example: Create User Response:

{
 "User": {
     “id”:123
     "link": ": "https://cloudedge.myhome.net/cloudedge/users/123",
   },
}

Update user

Verb URI Description
POST /cloudedge/users/id/action Reset the password or change any information for an user.

Error Response Code(s): computeFault (400, 500, ...), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405), itemNotFound (404), badMediaType (415),

In the Request body specify the type field you want to update.

This is can be used either to modify some characteristics of an account (for example, the mail address) or to reset a password.

This operation does not return a response body.

Example: email Update Request:

{
 “email” : "jmith@gmail.com"
}

Example: password Reset Request:

{
 “password” : "reset”
}

Delete User

Verb URI Description
DELETE /cloudedge/users/id Delete the {id] user.

Normal Response Code: 204

Error Response Code(s): computeFault (400, 500, ...), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405), itemNotFound (404)

This operation deletes a user from the system.

Specify the user ID as id in the URI.

This operation does not require a request body or return a response body.

Metrics

There is no formal metrics API, it is up to the user to develop a virtual machine that could handle this task accordingly to his/her specific needs.

Personal tools
Create a book