diff --git a/src/developers-guide/src/docbkx/content/specification.xml b/src/developers-guide/src/docbkx/content/api-specification.xml
similarity index 100%
rename from src/developers-guide/src/docbkx/content/specification.xml
rename to src/developers-guide/src/docbkx/content/api-specification.xml
diff --git a/src/developers-guide/src/docbkx/content/repository-specification.xml b/src/developers-guide/src/docbkx/content/repository-specification.xml
new file mode 100644
index 0000000..c34997d
--- /dev/null
+++ b/src/developers-guide/src/docbkx/content/repository-specification.xml
@@ -0,0 +1,1459 @@
+
+
+
+ Metadata-Repository API Specification
+
+
+
+ | Revision Date |
+ Summary of Changes |
+
+
+
+
+ | February 2, 2013 |
+
+
+
+ Initial
+
+
+ |
+
+
+
+
+ Introduction
+ Murano Metadata Repository is used to operate (store, display,
+ group and use for deployment) the metadata objects. It is the
+ simplest possible storage for metadata objects, without any
+ significant modifications in the existing Murano components.
+
+
+ Metadata object type
+
+
+ Name of supported metadata objects. For now there are 6 of them:
+
+
+ Service Manifest - manifests
+
+
+ Workflow - workflow
+
+
+ Heat templates - heat
+
+
+ Agent templates - agent
+
+
+ Scripts - scripts
+
+
+ UI definitions - ui
+
+
+
+
+
+
+ Service Manifest
+
+ Defines basic properties of the services. It binds together
+ metadata objects by defining the names of the files required for a
+ given service. The manifest should be defined as a yaml
+ file.
+
+
+
+ Workflow
+
+ Definition of workflow rules and actions needed to deploy a
+ service
+
+
+
+ Heat templates
+
+ A parametrized Heat template
+
+
+
+ Agent templates
+
+ A template for Agent execution plan (contains script imports
+ and commands to execute)
+
+
+
+ Scripts
+
+ A script which is referenced in execution plan and is
+ executed on the Agent. Conductor loads the content of this file,
+ base-64 encodes it and injects it into the execution plan
+
+
+
+ UI definitions
+
+ A definition of the dynamic User Interface for service
+ configuration in the Dashboard.
+
+
+
+ Return codes and errors
+ All REST API calls return the natural HTTP response codes for
+ the operations, e.g. a successful GET returns a HTTP 200, a
+ successful PUT returns a HTTP 201, a GET for a non-existent entity
+ returns HTTP 404, unauthorized operations return HTTP 401 or HTTP
+ 403, internal errors return HTTP 500.
+ Authentication
+ All requests include a Keystone authentication token header
+ (X-Auth-Token). Clients must authenticate with Keystone before
+ interacting with the Murano Repository Service.
+
+
+ v1
+ This chapter defines all available api calls for v1 version.
+ All definitions are listed without version prefix. Just add
+ "v1" to the beginning of any call. Example:
+ v1/client/ui
+
+ Client API
+ This section describes API calls for Metadata Repository
+ clients.
+
+ Get archive for a specified client
+ Call
+
+ Get archive for a specified client
+
+
+
+
+
+
+ Method
+ URI
+ Description
+
+
+
+
+ GET
+ /client/<client_type>
+ Returns archive with all metadata objects for specified
+ client for all active services
+
+
+
+
+
+ Parameters
+
+
+
+
+
+
+ Parameter
+ Description
+ Required
+
+
+
+
+ client_type
+ One of supported Murano Repository client: ui - Murano
+ Dashboard; conductor - Murano Conductor
+ true
+
+
+
+
+
+ Response Codes
+
+
+
+
+
+ Code
+ Description
+
+
+
+
+ 200
+ Archive with metadata objects successfully composed and
+ sent
+
+
+ 401
+ User is not authorized to access this tenant
+ resources
+
+
+ 404
+ Client_type is not supported
+
+
+ 304
+ Returns empty body if the hash matches the hashsum of
+ current version of the metadata objects archive
+
+
+
+
+ Payload
+ None
+ Returns
+ This call returns an array of bytes represents tar.gz
+ archive
+
+
+ Download the service definition
+
+ Download the service definition
+
+
+
+
+
+
+ Method
+ URI
+ Description
+
+
+
+
+ GET
+ /client/services/<full_service_name>
+ Returns a tar.gz archive containing service definition
+ along with all referenced metadata objects, directory structure
+ of metadata objects is preserved
+
+
+
+
+
+ Parameters
+
+
+
+
+
+
+ Parameter
+ Description
+ Required
+
+
+
+
+ full_service_name
+ Identifies the type service (corresponds to
+ full_service_name in manifest)
+ true
+
+
+
+
+
+ Error Response Codes
+
+
+
+
+
+ Code
+ Description
+
+
+
+
+ 401
+ User is not authorized to access this tenant
+ resources
+
+
+ 404
+ Service with specified full_service_name does not
+ exist(there is no manifest file for this service)
+
+
+
+
+ Payload
+ None
+ Returns
+ This call returns an array of bytes represents tar.gz archive
+ with all files required for given service
+
+
+
+ Admin API
+
+ List Metadata Objects
+
+ List Metadata Objects
+
+
+
+
+
+
+ Method
+ URI
+ Description
+
+
+
+
+ GET
+ /admin/<object_type>/<path>
+ Returns a json-array containing the filenames of the
+ metadata objects of a given type in a given subdirectory.
+ Includes all subdirectories and their content
+
+
+
+
+
+ Parameters
+
+
+
+
+
+
+ Parameter
+ Description
+ Required
+
+
+
+
+ object_type
+ One of supported Murano Repository objects: workflow,
+ scripts, ui, agent, heat, manifests
+ true
+
+
+ path
+ May define a directory (which is present under the root
+ directory of the appropriate type of metadata). If specified,
+ the output will include only files and subdirectories of this
+ directory (the path will be relative to it).
+ false
+
+
+
+
+
+ Error Response Codes
+
+
+
+
+
+ Code
+ Description
+
+
+
+
+ 401
+ User is not authorized to access this tenant
+ resources
+
+
+ 404
+ Metadata object type or directory specified in path
+ parameter are not exist
+
+
+
+
+ Payload
+ None
+ Returns
+ This call returns list all files for specified object type
+ and path
+
+{
+ "ui": [
+ "MsSqlClusterServer.yaml",
+ "AspNetAppFarm.yaml",
+ "LinuxApache.yaml",
+ "WebServerFarm.yaml",
+ "Demo.yaml",
+ "WebServer.yaml",
+ "ActiveDirectory.yaml",
+ "MsSqlServer.yaml",
+ "AspNetApp.yaml",
+ "LinuxTelnet.yaml"
+ ]
+}
+
+
+
+ Get Metadata Object
+
+ Get Metadata Object
+
+
+
+
+
+
+ Method
+ URI
+ Description
+
+
+
+
+ GET
+ /admin/<object_type>/<file_name>
+ Returns a file containing specified metadata
+ object.
+
+
+
+
+
+ Parameters
+
+
+
+
+
+
+ Parameter
+ Description
+ Required
+
+
+
+
+ object_type
+ One of supported Murano Repository objects: workflow,
+ scripts, ui, agent, heat, manifests
+ true
+
+
+ file_name
+ Defines a filename of the file to be downloaded. Should
+ be relative to the root folder of the given type
+ true
+
+
+
+
+
+ Error Response Codes
+
+
+
+
+
+ Code
+ Description
+
+
+
+
+ 401
+ User is not authorized to access this tenant
+ resources
+
+
+ 404
+ Metadata object type or directory specified in path
+ parameter are not exist
+
+
+
+
+ Payload
+ None
+ Returns
+ This call returns an array of bytes represents a file
+
+
+ Upload a metadata object
+
+ Upload a metadata object
+
+
+
+
+
+
+
+ Method
+ URI
+ Content-Type
+ Description
+
+
+
+
+ POST
+ /admin/<object_type>/<path>
+ multipart/form-data
+ Submits a new metadata file of a given type. Attribute
+ "file" that points to the uploading file should be in
+ request.FILES section
+
+
+ POST
+
+ /admin/<object_type>/<path>?filename=test.yaml
+ application/octet-stream
+ Submits a new metadata file of a given type. Filename
+ parameter is required
+
+
+
+
+
+ Parameters
+
+
+
+
+
+
+ Parameter
+ Description
+ Required
+
+
+
+
+ object_type
+ identifies the type of the new metadata object. May be
+ one of the following: workflow, scripts, ui, agent, heat,
+ manifests
+ true
+
+
+ path
+ May define a directory (which is present under the root
+ directory of the appropriate type of metadata). If specified,
+ the file will be placed into that dir. If omitted, the file
+ will be placed into the root directory of the given metadata
+ type. This parameter may not be defined for files of type
+ “manifests”
+ false
+
+
+
+
+
+ Error Response Codes
+
+
+
+
+
+ Code
+ Description
+
+
+
+
+ 401
+ User is not authorized to access this tenant
+ resources
+
+
+ 404
+ The object_type is unknown or the path is set to an
+ non-existing directory
+
+
+ 400
+ The is no parameter 'file' in
+ request.FILES(for multipart/form-data Content type) or there is
+ no filename parameter in URL(for
+ application/octet-stream)
+
+
+
+
+ Payload
+ File will be stored on Metadata Repository Server in a
+ directory corresponds to given object type or in it's nested
+ directory
+ Returns
+
+ In case of successful result this call returns a json:
+
+{"result": "success"}
+
+
+
+
+ Create directory
+
+ Create directory
+
+
+
+
+
+
+ Method
+ URI
+ Description
+
+
+
+
+ PUT
+
+ /admin/<object_type>/<full_directory_name>
+ Creates a new directory in the given path
+
+
+
+
+
+ Parameters
+
+
+
+
+
+
+ Parameter
+ Description
+ Required
+
+
+
+
+ object_type
+ Identifies the type of the new metadata object. May be
+ one of the following: workflow, scripts, ui, agent,
+ heat.
+ true
+
+
+ full_directory_name
+ Defines a name of a new directory. If any components of
+ the path are missing, they will be created. If the directory
+ already exists, nothing will happen.
+ true
+
+
+
+
+
+ Error Response Codes
+
+
+
+
+
+ Code
+ Description
+
+
+
+
+ 401
+ User is not authorized to access this tenant
+ resources
+
+
+ 404
+ The object_type is unknown
+
+
+ 403
+ The object specified by full_path_to_object is directory
+ and it is not empty or object_type is set to
+ "manifest"
+
+
+
+
+ Payload
+ None
+ Returns
+
+ In case of successful result this call returns a json:
+
+{"result": "success"}
+
+
+
+
+ Delete metadata object or directory
+
+ Delete metadata object or directory
+
+
+
+
+
+
+ Method
+ URI
+ Description
+
+
+
+
+ DELETE
+
+ /admin/<object_type>/<full_path_to_object>
+ Deletes a metadata object or a directory. Directory
+ should be empty to be deleted
+
+
+
+
+
+ Parameters
+
+
+
+
+
+
+ Parameter
+ Description
+ Required
+
+
+
+
+ object_type
+ Identifies the type of the new metadata object. May be
+ one of the following: workflow, scripts, ui, agent, heat,
+ manifests.” typed cannot be specified, as subdirectories for
+ the service manifests cannot be created
+ true
+
+
+ full_path_to_object
+ Specifies the full path a file or a directory .
+ true
+
+
+
+
+
+ Error Response Codes
+
+
+
+
+
+ Code
+ Description
+
+
+
+
+ 401
+ User is not authorized to access this tenant
+ resources
+
+
+ 404
+ The object_type is unknown or the full_path_to_object is
+ set to an non-existing directory or object
+
+
+ 403
+ The object specified by full_path_to_object is a not
+ empty directory
+
+
+
+
+ Payload
+ File or directory with the given name permanently deletes
+ from Murano Metadata Repository Server
+ Returns
+
+ In case of successful result this call returns a json:
+
+{"result": "success"}
+
+
+
+
+ List all the services
+
+ List all the services
+
+
+
+
+
+
+ Method
+ URI
+ Description
+
+
+
+
+ GET
+ /admin/services
+ Returns a json-array containing all the info (version,
+ display name, author, etc) about each service except their
+ references to other metadata objects
+
+
+
+
+ Payload
+ None
+ Returns
+
+ In case of successful result this call returns a json:
+
+{
+ "services": [
+ {
+ "author": "Mirantis Inc.",
+ "description": "<strong> Demo Service </strong>
+ shows how Murano is working.",
+ "enabled": true,
+ "full_service_name": "demoService",
+ "service_display_name": "Demo Service",
+ "service_version": "",
+ "valid": true,
+ "version": "0.1"
+ },
+ {
+ "author": "Mirantis Inc.",
+ "description": "<strong> The Internet Information Service </strong>
+ sets up an IIS server and joins it into an existing domain",
+ "enabled": true,
+ "full_service_name": "webServer",
+ "service_display_name": "Internet Information Services",
+ "service_version": 1,
+ "valid": true,
+ "version": 0.1
+ }
+ ]
+}
+
+
+
+
+ List metadata objects of a given service
+
+ List metadata objects of a given service
+
+
+
+
+
+
+ Method
+ URI
+ Description
+
+
+
+
+ GET
+ /admin/services/<full_service_name>
+ Returns a json-dictionary containing the filenames of
+ the metadata objects referenced by a given service. Filenames
+ include all parent directories, all objects belonging to a
+ certain %metadata_type% are grouped into an array value for of
+ a %metadata_type% key.
+
+
+
+
+
+ Parameters
+
+
+
+
+
+
+ Parameter
+ Description
+ Required
+
+
+
+
+ full_service_name
+ Identifies the type service (corresponds to
+ full_service_name in manifest)
+ true
+
+
+
+
+
+ Error Response Codes
+
+
+
+
+
+ Code
+ Description
+
+
+
+
+ 401
+ User is not authorized to access this tenant
+ resources
+
+
+ 404
+ The full_service_name is unknown
+
+
+
+
+ Payload
+ None
+ Returns
+
+ This call returns a json:
+
+{
+ "agent": [
+ "Demo.template"
+ ],
+ "heat": [
+ "Demo.template",
+ "RouterInterface.template",
+ "Network.template",
+ "NNSecurity.template",
+ "Param.template",
+ "Subnet.template",
+ "InstancePortWSubnet.template",
+ "InstancePort.template"
+ ],
+ "scripts": [],
+ "ui": [
+ "Demo.yaml"
+ ],
+ "workflows": [
+ "Networking.xml",
+ "Common.xml",
+ "Demo.xml"
+ ]
+}
+
+
+
+
+ List meta information of a given service
+
+ List meta information of a given service
+
+
+
+
+
+
+ Method
+ URI
+ Description
+
+
+
+
+ GET
+ /admin/services/<full_service_name>/info
+ Returns a json-dictionary containing information of a
+ given service
+
+
+
+
+
+ Parameters
+
+
+
+
+
+
+ Parameter
+ Description
+ Required
+
+
+
+
+ full_service_name
+ Identifies the type service (corresponds to
+ full_service_name in manifest)
+ true
+
+
+
+
+
+ Error Response Codes
+
+
+
+
+
+ Code
+ Description
+
+
+
+
+ 401
+ User is not authorized to access this tenant
+ resources
+
+
+ 404
+ The full_service_name is unknown
+
+
+
+
+ Payload
+ None
+ Returns
+
+ This call returns a json:
+
+{
+ "author": "Mirantis Inc.",
+ "description": "Demo Service shows how Murano is working.",
+ "enabled": true,
+ "full_service_name": "demoService",
+ "service_display_name": "Demo Service",
+ "service_version": "",
+ "version": "0.1"
+}
+
+
+
+
+ Switch service parameter: enabled/disabled
+
+ Switch service parameter: enabled/disabled
+
+
+
+
+
+
+ Method
+ URI
+ Description
+
+
+
+
+ POST
+
+ /admin/services/<full_service_name>/toggle_enabled
+ Toggle current state of 'Enabled' parameter in
+ service manifest file
+
+
+
+
+
+ Parameters
+
+
+
+
+
+
+ Parameter
+ Description
+ Required
+
+
+
+
+ full_service_name
+ Identifies the type service (corresponds to
+ full_service_name in manifest)
+ true
+
+
+
+
+
+ Error Response Codes
+
+
+
+
+
+ Code
+ Description
+
+
+
+
+ 401
+ User is not authorized to access this tenant
+ resources
+
+
+ 404
+ The full_service_name is unknown
+
+
+
+
+ Payload
+ None
+ Returns
+
+ In case of successful result this call returns a json:
+
+{"result": "success"}
+
+
+
+
+ Upload the complete service definition
+
+ Upload the complete service definition
+
+
+
+
+
+
+
+ Method
+ URI
+ Content-Type
+ Description
+
+
+
+
+ POST
+ /admin/services
+ application/octet-stream
+ Uploads a tar.gz archive containing service definition
+ to be added to catalog along with the referenced metadata
+ objects. Metadata objects could be located in nested
+ directories, the directory structure will be preserved on
+ server-side
+
+
+ POST
+ /admin/services
+ multipart/form-data
+ Uploads a tar.gz archive containing service definition
+ to be added to catalog along with the referenced metadata
+ objects. Attribute "file" that points to the
+ uploading file should be in request.FILES section
+
+
+
+
+
+ Parameters
+
+
+
+
+
+
+ Parameter
+ Description
+ Required
+
+
+
+
+ full_service_name
+ Identifies the type service (corresponds to
+ full_service_name in manifest)
+ true
+
+
+
+
+
+ Error Response Codes
+
+
+
+
+
+ Code
+ Description
+
+
+
+
+ 401
+ User is not authorized to access this tenant
+ resources
+
+
+ 404
+ The full_service_name is unknown
+
+
+ 400
+ Uploading file is not tar.gz or archive is invalid
+ (archive structure not correspond to defined in config)
+
+
+
+
+ Payload
+ All files from archive are copied to corresponds location in
+ Metadata Service
+ Returns
+
+ In case of successful result this call returns a json:
+
+{"result": "success"}
+
+
+
+
+ Create or modify service definition
+
+ Create or modify service definition
+
+
+
+
+
+
+ Method
+ URI
+ Description
+
+
+
+
+ PUT
+ /admin/services/<full_service_name>
+ Create or modify manifest file. Request data should be a
+ json object If full_service_name is not specified new manifest
+ file will be created. Otherwise existent service definition
+ (manifest file) will be rewritten with the given data.
+
+
+
+
+
+ Parameters
+
+
+
+
+
+
+ Parameter
+ Description
+ Required
+
+
+
+
+ full_service_name
+ Identifies the type service (corresponds to
+ full_service_name in manifest)
+ false
+
+
+
+
+
+ Error Response Codes
+
+
+
+
+
+ Code
+ Description
+
+
+
+
+ 401
+ User is not authorized to access this tenant
+ resources
+
+
+ 404
+ The full_service_name is unknown
+
+
+ 400
+ If specified full_service_name is not equivalent to that
+ parameter in json or there is no json data in request
+
+
+
+
+ Payload
+ All files from archive are copied to corresponds location in
+ Metadata Service
+ Returns
+
+ In case of successful result this call returns a json:
+
+{"result": "success"}
+
+
+
+
+ Delete service from repository
+
+ Delete service from repository
+
+
+
+
+
+
+ Method
+ URI
+ Description
+
+
+
+
+ DELETE
+ /admin/services/<full_service_name>
+ Deletes a service from repository
+
+
+
+
+
+ Parameters
+
+
+
+
+
+
+ Parameter
+ Description
+ Required
+
+
+
+
+ full_service_name
+ Identifies the type service (corresponds to
+ full_service_name in manifest)
+ true
+
+
+
+
+
+ Error Response Codes
+
+
+
+
+
+ Code
+ Description
+
+
+
+
+ 401
+ User is not authorized to access this tenant
+ resources
+
+
+ 404
+ The full_service_name is unknown
+
+
+
+
+ Payload
+ All files from archive are copied to corresponds location in
+ Metadata Service
+ Returns
+
+ In case of successful result this call returns a json:
+
+{"result": "success"}
+
+
+
+
+ Reset cache
+
+ Reset cache
+
+
+
+
+
+
+ Method
+ URI
+ Description
+
+
+
+
+ POST
+ /admin/reset_caches
+ Clear server cache in case of manual data
+ modification
+
+
+
+
+ Payload
+ None
+ Returns
+
+ In case of successful result this call returns a json:
+
+{"result": "success"}
+
+
+
+
+
+
diff --git a/src/developers-guide/src/docbkx/developers-guide.xml b/src/developers-guide/src/docbkx/developers-guide.xml
index 27f6913..7c5b512 100644
--- a/src/developers-guide/src/docbkx/developers-guide.xml
+++ b/src/developers-guide/src/docbkx/developers-guide.xml
@@ -37,7 +37,8 @@
-
+
+