Murano API v1 specification

General information

  • Introduction

    Murano Service API is a programmatic interface used for interaction with Murano. Other interaction mechanisms like Murano Dashboard or Murano CLI should use API as underlying protocol for interaction. * Allowed HTTPs requests

    • POST : To create a resource
    • GET : Get a resource or list of resources
    • DELETE : To delete resource
    • PATCH : To update a resource
  • Description Of Usual Server Responses

    • 200 OK - the request was successful.
    • 201 Created - the request was successful and a resource was created.
    • 204 No Content - the request was successful but there is no representation to return (i.e. the response is empty).
    • 400 Bad Request - the request could not be understood or required parameters were missing.
    • 401 Unauthorized - authentication failed or user didn’t have permissions for requested operation.
    • 403 Forbidden - access denied.
    • 404 Not Found - resource was not found
    • 405 Method Not Allowed - requested method is not supported for resource.
  • Response of POSTs and PUTs

    All POST and PUT requests by convention should return the created object (in the case of POST, with a generated ID) as if it was requested by GET.

  • Authentication

    All requests include a Keystone authentication token header (X-Auth-Token). Clients must authenticate with Keystone before interacting with the Murano service.

Glossary

  • Environment

    Environment is a set of applications managed by a single tenant. They could be related logically with each other or not. Applications within single Environment may comprise some complex configuration while applications in different Environments are always independent from one another. Each Environment is associated with single OpenStack project (tenant).

  • Session

    Since Murano environment are available for local modification for different users and from different locations, it’s needed to store local modifications somewhere. So sessions were created to provide this opportunity. After user adds application to the environment - new session is created. After user sends environment to deploy, session with set of applications changes status to deploying and all other open sessions for that environment becomes invalid. One session could be deployed only once.

  • Object Model

    Applications are defined in MuranoPL object model, which is defined as JSON object. Murano API doesn’t know anything about it.

  • Package

    A .zip archive, containing instructions for an application deployment.

Environment API

Attribute Type Description
id string Unique ID
name string User-friendly name
created datetime Creation date and time in ISO format
updated datetime Modification date and time in ISO format
tenant_id string OpenStack tenant ID
version int Current version
networking string Network settings
status string Deployment status: ready, pending, deploying

Common response codes

Code Description
200 Operation completed successfully
401 User is not authorized to perform the operation

List Environments

Method URI Description
GET /environments Get a list of existing Environments

This call returns list of environments. Only the basic properties are returned.

{
    "environments": [
        {
            "status": "ready",
            "updated": "2014-05-14T13:02:54",
            "networking": {},
            "name": "test1",
            "created": "2014-05-14T13:02:46",
            "tenant_id": "726ed856965f43cc8e565bc991fa76c3",
            "version": 0,
            "id": "2fa5ab704749444bbeafe7991b412c33"
        },
        {
            "status": "ready",
            "updated": "2014-05-14T13:02:55",
            "networking": {},
            "name": "test2",
            "created": "2014-05-14T13:02:51",
            "tenant_id": "726ed856965f43cc8e565bc991fa76c3",
            "version": 0,
            "id": "744e44812da84e858946f5d817de4f72"
        }
    ]
}

Create Environment

Attribute Type Description
name string Environment name; only alphanumeric characters and ‘-‘
Method URI Description
POST /environments Create new Environment
  • Content-Type application/json

  • Example

    {“name”: “env_name”}

{
    "id": "ce373a477f211e187a55404a662f968",
    "name": "env_name",
    "created": "2013-11-30T03:23:42Z",
    "updated": "2013-11-30T03:23:44Z",
    "tenant_id": "0849006f7ce94961b3aab4e46d6f229a",
    "version": 0
}

Update Environment

Attribute Type Description
name string Environment name; only alphanumeric characters and ‘-‘
Method URI Description
PUT /environments/<env_id> Update an existing Environment
  • Content-Type application/json
  • Example {“name”: “env_name_changed”}
Content-Type
application/json
{
    "id": "ce373a477f211e187a55404a662f968",
    "name": "env_name_changed",
    "created": "2013-11-30T03:23:42Z",
    "updated": "2013-11-30T03:45:54Z",
    "tenant_id": "0849006f7ce94961b3aab4e46d6f229a",
    "version": 0
}

Get Environment Details

Return information about environment itself and about applications, including to this environment.

Method URI Header Description
GET /environments/{id} X-Configuration-Session (optional) Response detailed information about Environment including child entities
Content-Type
application/json
{
    "status": "ready",
    "updated": "2014-05-14T13:12:26",
    "networking": {},
    "name": "quick-env-2",
    "created": "2014-05-14T13:09:55",
    "tenant_id": "726ed856965f43cc8e565bc991fa76c3",
    "version": 1,
    "services": [
        {
            "instance": {
                "flavor": "m1.medium",
                "image": "cloud-fedora-v3",
                "name": "exgchhv6nbika2",
                "ipAddresses": [
                    "10.0.0.200"
                ],
                "?": {
                    "type": "io.murano.resources.Instance",
                    "id": "14cce9d9-aaa1-4f09-84a9-c4bb859edaff"
                }
            },
            "name": "rewt4w56",
            "?": {
                "status": "ready",
                "_26411a1861294160833743e45d0eaad9": {
                    "name": "Telnet"
                },
                "type": "io.murano.apps.linux.Telnet",
                "id": "446373ef-03b5-4925-b095-6c56568fa518"
            }
        }
    ],
    "id": "20d4a012628e4073b48490a336a8acbf"
}

Delete Environment

Method URI Description
DELETE /environments/{id} Remove specified Environment.

Environment Configuration API

Multiple sessions could be opened for one environment simultaneously, but only one session going to be deployed. First session that starts deploying is going to be deployed; other ones become invalid and could not be deployed at all. User could not open new session for environment that in deploying state (that’s why we call it “almost lock free” model).

Attribute Type Description
id string Session unique ID
environment_id string Environment that going to be modified during this session
created datetime Creation date and time in ISO format
updated datetime Modification date and time in ISO format
user_id string Session owner ID
version int Environment version for which configuration session is opened
state string Session state. Could be: open, deploying, deployed

Configure Environment / Open session

During this call new working session is created, and session ID should be sent in a request header with name X-Configuration-Session.

Method URI Description
POST /environments/<env_id>/configure Creating new configuration session
Content-Type
application/json
{
    "updated": datetime.datetime(2014, 5, 14, 14, 17, 58, 949358),
    "environment_id": "744e44812da84e858946f5d817de4f72",
    "ser_id": "4e91d06270c54290b9dbdf859356d3b3",
    "created": datetime.datetime(2014, 5, 14, 14, 17, 58, 949305),
    "state": "open", "version": 0L, "id": "257bef44a9d848daa5b2563779714820"
 }
Code Description
200 Session created successfully
401 User is not authorized to access this session
403 Could not open session for environment, environment has deploying status

Deploy Session

With this request all local changes made within environment start to deploy on Openstack.

Method URI Description
POST /environments/<env_id>/sessions/ <session_id>/deploy
Deploy changes made in session
with specified session_id
Code Description
200 Session status changes to deploying
401 User is not authorized to access this session
403 Session is already deployed or deployment is in progress

Get Session Details

Method URI Description
GET /environments/<env_id>/sessions/ <session_id> Get details about session with specified session_id
{
    "id": "4aecdc2178b9430cbbb8db44fb7ac384",
    "environment_id": "4dc8a2e8986fa8fa5bf24dc8a2e8986fa8",
    "created": "2013-11-30T03:23:42Z",
    "updated": "2013-11-30T03:23:54Z",
    "user_id": "d7b501094caf4daab08469663a9e1a2b",
    "version": 0,
    "state": "deploying"
}
Code Description
200 Session details information received
401 User is not authorized to access this session
403 Session is invalid

Delete Session

Method URI Description
DELETE /environments/<env_id>/sessions/ <session_id> Delete session with specified session_id
Code Description
200 Session is deleted successfully
401 User is not authorized to access this session
403 Session is in deploying state and could not be deleted

Environment Deployments API

Environment deployment API allows to track changes of environment status, deployment events and errors. It also allows to browse deployment history.

List Deployments

Returns information about all deployments of the specified environment.

Method URI Description
GET /environments/<env_id>/deployments Get list of environment deployments
Content-Type
application/json
{
    "deployments": [
        {
            "updated": "2014-05-15T07:24:21",
            "environment_id": "744e44812da84e858946f5d817de4f72",
            "description": {
                "services": [
                    {
                        "instance": {
                            "flavor": "m1.medium",
                            "image": "cloud-fedora-v3",
                            "?": {
                                "type": "io.murano.resources.Instance",
                                "id": "ef729199-c71e-4a4c-a314-0340e279add8"
                            },
                            "name": "xkaduhv7qeg4m7"
                        },
                        "name": "teslnet1",
                        "?": {
                            "_26411a1861294160833743e45d0eaad9": {
                                "name": "Telnet"
                            },
                            "type": "io.murano.apps.linux.Telnet",
                            "id": "6e437be2-b5bc-4263-8814-6fd57d6ddbd5"
                        }
                    }
                ],
                "defaultNetworks": {
                    "environment": {
                        "name": "test2-network",
                        "?": {
                            "type": "io.murano.lib.networks.neutron.NewNetwork",
                            "id": "b6a1d515434047d5b4678a803646d556"
                        }
                    },
                    "flat": null
                },
                "name": "test2",
                "?": {
                    "type": "io.murano.Environment",
                    "id": "744e44812da84e858946f5d817de4f72"
                }
            },
            "created": "2014-05-15T07:24:21",
            "started": "2014-05-15T07:24:21",
            "finished": null,
            "state": "running",
            "id": "327c81e0e34a4c93ad9b9052ef42b752"
        }
    ]
}
Code Description
200 Deployments information received successfully
401 User is not authorized to access this environment

Application Management API

All applications should be created within an environment and all environment modifications are held within the session. Local changes apply only after successful deployment of an environment session.

Get Application Details

Using GET requests to applications endpoint user works with list containing all applications for specified environment. User can request whole list, specific application, or specific attribute of specific application using tree traversing. To request specific application, user should add to endpoint part an application id, e.g.: /environments/<env_id>/services/<application_id>. For selection of specific attribute on application, simply appending part with attribute name will work. For example to request application name, user should use next endpoint: /environments/<env_id>/services/<application_id>/name

Method URI Header
GET /environments/<env_id>/services<app_id> X-Configuration-Session (optional)

Parameters:

  • env_id - environment ID, required
  • app_id - application ID, optional
Content-Type
application/json
{
    "instance": {
        "flavor": "m1.medium",
        "image": "cloud-fedora-v3",
        "?": {
            "type": "io.murano.resources.Instance",
            "id": "060715ff-7908-4982-904b-3b2077ff55ef"
        },
        "name": "hbhmyhv6qihln3"
    },
    "name": "dfg34",
    "?": {
        "status": "pending",
        "_26411a1861294160833743e45d0eaad9": {
            "name": "Telnet"
        },
        "type": "io.murano.apps.linux.Telnet",
        "id": "6e7b8ad5-888d-4c5a-a498-076d092a7eff"
    }
}

POST applications

New application can be added to the Murano environment using session. Result JSON is calculated in Murano dashboard, which based on UI definition

Content-Type
application/json
Method URI Header
POST /environments/<env_id>/services X-Configuration-Session
{
  "instance": {
    "flavor": "m1.medium",
    "image": "clod-fedora-v3",
    "?": {
      "type": "io.murano.resources.Instance",
      "id": "bce8308e-5938-408b-a27a-0d3f0a2c52eb"
    },
    "name": "nhekhv6r7mhd4"
  },
  "name": "sdf34sadf",
  "?": {
    "_26411a1861294160833743e45d0eaad9": {
      "name": "Telnet"
    },
    "type": "io.murano.apps.linux.Telnet",
    "id": "190c8705-5784-4782-83d7-0ab55a1449aa"
  }
}

Created application returned

Content-Type
application/json
{
    "instance": {
        "flavor": "m1.medium",
        "image": "cloud-fedora-v3",
        "?": {
            "type": "io.murano.resources.Instance",
            "id": "bce8308e-5938-408b-a27a-0d3f0a2c52eb"
        },
        "name": "nhekhv6r7mhd4"
    },
    "name": "sdf34sadf",
    "?": {
        "_26411a1861294160833743e45d0eaad9": {
            "name": "Telnet"
        },
        "type": "io.murano.apps.linux.Telnet",
        "id": "190c8705-5784-4782-83d7-0ab55a1449a1"
    }
}

Delete application from environment

Delete one or all applications from the environment

Method URI Header
DELETE /environments/<env_id>/services/<app_id> X-Configuration-Session(optional)

Parameters:

  • env_id - environment ID, required
  • app_id - application ID, optional

Statistic API

Statistic API intends to provide billing feature

Instance Environment Statistics

Get information about all deployed instances in the specified environment

Method URI
GET /environments/<env_id>/instance-statistics/raw/<instance_id>

Parameters:

  • env_id - environment ID, required
  • instance_id - ID of the instance for which need to provide statistic information, optional
Attribute Type Description
type int Code of the statistic object; 200 - instance, 100 - application
type_name string Class name of the statistic object
instance_id string Id of deployed instance
active bool Instance status
type_title string User-friendly name for browsing statistic in UI
duration int Seconds of instance uptime
Content-Type
application/json
[
    {
        "type": 200,
        "type_name": "io.murano.resources.Instance",
        "instance_id": "ef729199-c71e-4a4c-a314-0340e279add8",
        "active": true,
        "type_title": null,
        "duration": 1053,
    }
]
Method URI
GET /environments/<env_id>/instance-statistics/aggregated
Attribute Type Description
type int Code of the statistic object; 200 - instance, 100 - application
duration int Amount uptime of specified type objects
count int Quantity of specified type objects
Content-Type
application/json
[
    {
        "duration": 720,
        "count": 2,
        "type": 200
    }
]

General Request Statistics

Method URI
GET /stats
Attribute Type Description
requests_per_tenant int Number of incoming requests for user tenant
errors_per_second int Class name of the statistic object
errors_count int Class name of the statistic object
requests_per_second float Average number of incoming request received in one second
requests_count int Number of all requests sent to the server
cpu_percent bool Current cpu usage
cpu_count int Available cpu power is cpu_count * 100%
host string Server host-name
average_response_time float Average time response waiting, seconds
Content-Type
application/json
[
    {
        "updated": "2014-05-15T08:26:17",
        "requests_per_tenant": "{\"726ed856965f43cc8e565bc991fa76c3\": 313}",
        "created": "2014-04-29T13:23:59",
        "cpu_count": 2,
        "errors_per_second": 0,
        "requests_per_second": 0.0266528,
        "cpu_percent": 21.7,
        "host": "fervent-VirtualBox",
        "error_count": 0,
        "request_count": 320,
        "id": 1,
        "average_response_time": 0.55942
    }
]

Application Catalog API

Manage application definitions in the Application Catalog. You can browse, edit and upload new application packages (.zip.package archive with all data that required for a service deployment).

Packages

Methods for application package management

Package Properties

  • id: guid of a package (fully_qualified_name can also be used for some API functions)
  • fully_qualified_name: fully qualified domain name - domain name that specifies exact application location
  • name: user-friendly name
  • type: package type, “library” or “application”
  • description: text information about application
  • author: name of application author
  • tags: list of short names, connected with the package, which allows to search applications easily
  • categories: list of application categories
  • class_definition: list of class names used by a package
  • is_public: determines whether the package is shared for other tenants
  • enabled: determines whether the package is browsed in the Application Catalog
  • owner_id: id of a tenant which user not an owned the package

/v1/catalog/packages?{marker}{limit}{order_by}{type}{category}{fqn}{owned}{class_name} [GET]

This is the compound request to list and search through application catalog. If there are no search parameters all packages that is_public, enabled and belong to the user’s tenant will be listed. Default order is by ‘created’ field. For an admin role all packages are available.

Parameters

Attribute Type Description
marker string A package identifier marker may be specified. When present only packages which occur after the identifier ID will be listed
limit string When present the maximum number of results returned will not exceed the specified value. The typical pattern of limit and marker is to make an initial limited request and then to use the ID of the last package from the response as the marker parameter in a subsequent limited request.
order_by string Allows to sort packages by: fqn, name, created. Created is default value.
type string Allows to point a type of package: application, library
category string Allows to point a categories for a search
fqn string Allows to point a fully qualified package name for a search
owned bool Search only from packages owned by user tenant
include_disabled bool Include disabled packages in a the result
search string Gives opportunity to search specified data by all the package parameters
class_name string Search only for packages, that use specified class

Response 200 (application/json)

{"packages": [
             {
               "id": "fed57567c9fa42c192dcbe0566f8ea33",
                "fully_qualified_name" : "com.example.murano.services.linux.telnet",
                "is_public": false,
                "name": "Telnet",
                "type": "linux",
                "description": "Installs Telnet service",
                "author": "Openstack, Inc.",
                "created": "2014-04-02T14:31:55",
                "enabled": true,
                "tags": ["linux", "telnet"],
                "categories": ["Utility"],
                "owner_id": "fed57567c9fa42c192dcbe0566f8ea40"
             },
             {
               "id": "fed57567c9fa42c192dcbe0566f8ea31",
               "fully_qualified_name": "com.example.murano.services.windows.WebServer",
               "is_public": true,
               "name": "Internet Information Services",
               "type": "windows",
               "description": "The  Internet Information Service sets up an IIS server and joins it into an existing domain",
               "author": "Openstack, Inc.",
               "created": "2014-04-02T14:31:55",
               "enabled": true,
               "tags": ["windows", "web"],
               "categories": ["Web"],
               "owner_id": "fed57567c9fa42c192dcbe0566f8ea40"
             }]
 }

/v1/catalog/packages

See the example of multipart/form-data request, It should contain two parts - text (json string) and file object

Request (multipart/form-data)

Content-type: multipart/form-data, boundary=AaB03x
Content-Length: $requestlen

--AaB03x
content-disposition: form-data; name="submit-name"

--AaB03x
Content-Disposition: form-data; name="JsonString"
Content-Type: application/json

{"categories":["web"] , "tags": ["windows"], "is_public": false, "enabled": false}
`categories` - array, required
`tags` - array, optional
`name` - string, optional
`description` - string, optional
`is_public` - bool, optional
`enabled` - bool, optional

--AaB03x
content-disposition: file; name="file"; filename="test.tar"
Content-Type: targz
Content-Transfer-Encoding: binary

$binarydata
--AaB03x--

Response 200 (application/json)

{
    "updated": "2014-04-03T13:00:13",
    "description": "A domain service hosted in Windows environment by using Active Directory Role",
    "tags": ["windows"],
    "is_public": true,
    "id": "8f4f09bd6bcb47fb968afd29aacc0dc9",
    "categories": ["test1"],
    "name": "Active Directory",
    "author": "Mirantis, Inc",
    "created": "2014-04-03T13:00:13",
    "enabled": true,
    "class_definition": [
        "com.mirantis.murano.windows.activeDirectory.ActiveDirectory",
        "com.mirantis.murano.windows.activeDirectory.SecondaryController",
        "com.mirantis.murano.windows.activeDirectory.Controller",
        "com.mirantis.murano.windows.activeDirectory.PrimaryController"
    ],
    "fully_qualified_name": "com.mirantis.murano.windows.activeDirectory.ActiveDirectory",
    "type": "Application",
    "owner_id": "fed57567c9fa42c192dcbe0566f8ea40"
}

/v1/catalog/packages/{id} [GET]

Display details for a package.

Parameters

id (required) Hexadecimal id (or fully qualified name) of the package

Response 200 (application/json)

{
    "updated": "2014-04-03T13:00:13",
    "description": "A domain service hosted in Windows environment by using Active Directory Role",
    "tags": ["windows"],
    "is_public": true,
    "id": "8f4f09bd6bcb47fb968afd29aacc0dc9",
    "categories": ["test1"],
    "name": "Active Directory",
    "author": "Mirantis, Inc",
    "created": "2014-04-03T13:00:13",
    "enabled": true,
    "class_definition": [
        "com.mirantis.murano.windows.activeDirectory.ActiveDirectory",
        "com.mirantis.murano.windows.activeDirectory.SecondaryController",
        "com.mirantis.murano.windows.activeDirectory.Controller",
        "com.mirantis.murano.windows.activeDirectory.PrimaryController"
    ],
    "fully_qualified_name": "com.mirantis.murano.windows.activeDirectory.ActiveDirectory",
    "type": "Application",
    "owner_id": "fed57567c9fa42c192dcbe0566f8ea40"
}

Response 403

  • In attempt to get non-public package by user whose tenant is not an owner of this package.

Response 404

  • In case specified package id doesn’t exist.

/v1/catalog/packages/{id} [PATCH]

Allows to edit mutable fields (categories, tags, name, description, is_public, enabled). See the full specification here.

Parameters

id (required) Hexadecimal id (or fully qualified name) of the package

Allowed operations:

[
    { "op": "add", "path": "/tags", "value": [ "foo", "bar" ] },
    { "op": "add", "path": "/categories", "value": [ "foo", "bar" ] },
    { "op": "remove", "path": "/tags", ["foo"] },
    { "op": "remove", "path": "/categories", ["foo"] },
    { "op": "replace", "path": "/tags", "value": [] },
    { "op": "replace", "path": "/categories", "value": ["bar"] },
    { "op": "replace", "path": "/is_public", "value": true },
    { "op": "replace", "path": "/enabled", "value": true },
    { "op": "replace", "path": "/description", "value":"New description" },
    { "op": "replace", "path": "/name", "value": "New name" }
]

Request 200 (application/murano-packages-json-patch)

[
 { "op": "add", "path": "/tags", "value": [ "windows", "directory"] },
 { "op": "add", "path": "/categories", "value": [ "Directory" ] }
]

Response 200 (application/json)

{
    "updated": "2014-04-03T13:00:13",
    "description": "A domain service hosted in Windows environment by using Active Directory Role",
    "tags": ["windows", "directory"],
    "is_public": true,
    "id": "8f4f09bd6bcb47fb968afd29aacc0dc9",
    "categories": ["test1"],
    "name": "Active Directory",
    "author": "Mirantis, Inc",
    "created": "2014-04-03T13:00:13",
    "enabled": true,
    "class_definition": [
        "com.mirantis.murano.windows.activeDirectory.ActiveDirectory",
        "com.mirantis.murano.windows.activeDirectory.SecondaryController",
        "com.mirantis.murano.windows.activeDirectory.Controller",
        "com.mirantis.murano.windows.activeDirectory.PrimaryController"
    ],
    "fully_qualified_name": "com.mirantis.murano.windows.activeDirectory.ActiveDirectory",
    "type": "Application",
    "owner_id": "fed57567c9fa42c192dcbe0566f8ea40"
}

Response 403

  • An attempt to update immutable fields
  • An attempt to perform operation that is not allowed on the specified path
  • An attempt to update non-public package by user whose tenant is not an owner of this package

Response 404

  • An attempt to update package that doesn’t exist

/v1/catalog/packages/{id} [DELETE]

Parameters

id (required) Hexadecimal id (or fully qualified name) of the package to delete

Response 404

  • An attempt to delete package that doesn’t exist

Download application data

/v1/catalog/packages/{id}/download [GET]

Get application definition package

Parameters

  • id (required) Hexadecimal id (or fully qualified name) of the package

Response 200 (application/octetstream)

The sequence of bytes representing package content

Response 404

Specified package id doesn’t exist

/v1/catalog/packages/{id}/ui [GET]

Retrieve UI definition for a application which described in a package with provided id

Parameters

  • id (required) Hexadecimal id (or fully qualified name) of the package

Response 200 (application/octet-stream)

The sequence of bytes representing UI definition

Response 404

Specified package id doesn’t exist

Response 403

Specified package is not public and not owned by user tenant, performing the request

Response 404

  • Specified package id doesn’t exist

Retrieve application logo which described in a package with provided id

/v1/catalog/packages/{id}/logo [GET]

Parameters

id (required) Hexadecimal id (or fully qualified name) of the package

Response 200 (application/octet-stream)

The sequence of bytes representing application logo

Response 403

Specified package is not public and not owned by user tenant, performing the request

Response 404

Specified package is not public and not owned by user tenant, performing the request

Categories

/v1/catalog/packages/categories [GET]

Retrieve list of all available application categories

Response 200 (application/json)

{
    "categories": ["Web service", "Directory", "Database", "Storage"]
}