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 (PRELIMINARY) - FIWARE Forge Wiki

Cloud Edge Service Management API Specification (PRELIMINARY)

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction

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

Service Platform Management API Core

The Service Platform API allows to manage 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 implements Service Platform Management API.
  • For the Cloud Operators, this specification indicates the interface to be provided in order to 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

Note that the 1st version of this API (and the 1st delivery of the Cloud Proxy Software) was XML-RPC compliant and not RESTFull. This version of this document obsoletes the previous ones.


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.


The picture below gives an overview of the different URI that can be used in the API.

File:Uri.png

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 are 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 contains 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

Synchronous Faults

For the set of faults that a Cloud Proxy service can return, see Synchronous Faults

Asynchronous Faults

No asynchronous faults specified.

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

Version detail

Verb URI Description
GET /cloudedge/platform/version Retrieve the full version information about the running Cloud Edge Service software.

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 are detailed in the response body:

Example of version info Response:

{
 "version": {
   "major": 1,
   "minor": 3
 }
}

Get Platform Resources

Verb URI Description
GET /cloudedge/platform/resources List the capabilities 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 are detailed in the response body:

Type SubType Description
CPU type Provides the type of CPU that is running in the platform
vcpu Number of virtual CPUs that can be shared to a Virtual Application
RAM Amount of available memory (in Magabytes) that can be dedicated to an instance
disk Amount of available disk space (in Megabits) that can be used by any instance
Other devices (USB; PCI ...) Description of other hardware capabilities. Refer to Libvirt description for the detailed explanation of each sub topics.

Example: get platform resources Response:

{
 "cpu": {
   "type" : "i386",
   "vcpu" : 2
 },
 "ram" : 1024,
 "disk" : 5000,
 "usb" {
     "class" : "unknown",
     "vendor" : "0x10c4",
     "product" : "0xea60"
  }
}

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": "flickr++",
     "owner_id": 6789,
     "status": "ACTIVE",
     "created_by": 78945
     "created_at": "2012-06-25T15:23:33+02:00",
     "updated_at": "2012-09-12T17:16:38+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 register 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": "flickr++",
     "imageRef": “http://www.example.com/images/flick.tar.gz”,
   }
}


Example: Register image Response

{
 "image": {
     "id": 237,
     "name": "flickr++",
     "status": "ACTIVE",
     "created_at": "2012-06-25T15:23:33+02:00",
     "link": "https://cloudedge.myhome.net/cloudedge/images/237"
   }
}

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:

{
 "instances":  {
     "id": 237,
     "name": "test-instance-237",
     "status": "running",
     "image": {
       "id": 61,
       "name": "test",
       "link": "https://cloudedge.myhome.net/cloudedge/images/61"
     },
     "created_by": 789,
     "ip": "10.0.3.2",
     "created_at": "2012-06-25T15:23:33+02:00",
     "updated_at": "2012-09-12T17:16:38+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, freeze, 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)

Specific attributes: for stop and reboot action, you can specify the type of stop you want. This is specified by adding “type” attribute to your request. There is two defined values:

SOFT: (default value) for stopping the instance gracefully. HARD: equivalent to power cycling the instance


This operation does not return a response body.

Example: Action Start request:

{
           “start” : null
}


Example: Action Stop request:

{         
           “stop” : {
                       “type” : “HARD”
           }
}

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 administrated 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 administrate “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 delete 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

List Metrics

Verb URI Description
GET /cloudedge/instance/id/metrics List all the valid metrics for 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)

This operation list the mectrics that are visible by the account.

This operation do not require a request body.

Example: List metrics Response:

{
 "metrics": [
   {
     "CPUUtilization" : {
       "statistics" : [ "min", "max", "average" ]
     }
   },
   {
     "NetworkIn" : {
       "statistics" : [ "max", "average" ]
     }
   }
   {
     "Network0ut" : {
       "statistics" : [ "max", "average" ]
     }
   }
 ]
}


List Metric Statistics

Verb URI Description
GET /cloudedge/instance/id/metrics/statistics get statistics for the specified metric.

Normal Response Code(s): 200

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

The following list describes the required attributes that need be specified in the request body:

  • Statistics: The metric statistics to return. For information about specific statistics refer to the values returned by the operation that list the Metrics.
  • endTime: The time stamp to use for determining the last datapoint to return. This value must be specified in ISO 8601 format.
  • startTime: The time stamp to use for determining the first datapoint to return. This value must be specified in ISO 8601 format.
  • period: The granularity of the returned datapoints. Valid value must be : "minute", "5minutes", "hour", "day", "month", "year"

Example: get metric statistics Request:

{
 "CPUUtilization" : {
   "statistics" : "average",
   "endTime" : "2012-09-19 07:07:02Z",
   "startTime" : "2012-09-19 07:00:00Z",
   "period" : "minute"
   }

}

Example: metrics Response:

{
 "CPUUtilization" : {
   "statistics" : "average",
   "unit" : "Kilobits/Second",
   "datapoints" {
     "2012-09-19 07:00:00Z" : 230,
     "2012-09-19 07:01:00Z" : 200,
     "2012-09-19 07:02:00Z" : 30,
     "2012-09-19 07:02:00Z" : 130,
     "2012-09-19 07:03:00Z" : 550,
     "2012-09-19 07:04:00Z" : 402,
     "2012-09-19 07:05:00Z" : 20,
     "2012-09-19 07:06:00Z" : 23,
   }
}
Personal tools
Create a book