Difference between revisions of "Solum/API"
m (→Platform) |
Adrian Otto (talk | contribs) |
||
Line 14: | Line 14: | ||
|} | |} | ||
{| class="wikitable" | {| class="wikitable" | ||
− | | GET || /assemblies || Get a list of the <code> | + | | GET || /assemblies || Get a list of the <code>assembly</code> resources for this tenant |
|- | |- | ||
− | | POST || /assemblies || Create a new <code> | + | | POST || /assemblies || Create a new <code>assembly</code> resource |
|- | |- | ||
− | | GET || /assemblies/{id} || Get a specific <code> | + | | GET || /assemblies/{id} || Get a specific <code>assembly</code> resource |
|- | |- | ||
− | | PUT || /assemblies/{id} || Update a complete <code> | + | | PUT || /assemblies/{id} || Update a complete <code>assembly</code> resource |
|- | |- | ||
− | | PATCH || /assemblies/{id} || Update select attributes of an <code> | + | | PATCH || /assemblies/{id} || Update select attributes of an <code>assembly</code> resource |
|- | |- | ||
− | | DELETE || /assemblies/{id} || Delete this <code> | + | | DELETE || /assemblies/{id} || Delete this <code>assembly</code> resource. |
|} | |} | ||
{| class="wikitable" | {| class="wikitable" | ||
− | | GET || / | + | | GET || /plans || Get a list of the <code>plan</code> resources for this tenant |
|- | |- | ||
− | | POST || / | + | | POST || /plans || Create a new <code>plan</code> resource |
|- | |- | ||
− | | GET || / | + | | GET || /plans/{id} || Get a specific <code>plan</code> resource |
|- | |- | ||
− | | PUT || / | + | | PUT || /plans/{id} || Update a complete <code>plan</code> resource |
|- | |- | ||
− | | PATCH || / | + | | PATCH || /plans/{id} || Update select attributes of a <code>plan</code> resource |
|- | |- | ||
− | | DELETE || / | + | | DELETE || /plans/{id} || Delete this <code>plan</code> resource. |
|} | |} | ||
{| class="wikitable" | {| class="wikitable" | ||
− | | GET || / | + | | GET || /components || Get a list of the <code>component</code> resources for this tenant |
|- | |- | ||
− | | POST || / | + | | POST || /components || Create a new <code>component</code> resource |
|- | |- | ||
− | | GET || / | + | | GET || /components/{id} || Get a specific <code>component</code> resource |
|- | |- | ||
− | | PUT || / | + | | PUT || /components/{id} || Update a complete <code>component</code> resource |
|- | |- | ||
− | | PATCH || / | + | | PATCH || /components/{id} || Update select attributes of an <code>component</code> resource |
|- | |- | ||
− | | DELETE || / | + | | DELETE || /components/{id} || Delete this <code>component</code> resource. |
|} | |} | ||
{| class="wikitable" | {| class="wikitable" | ||
− | | GET || / | + | | GET || /services || Get a list of the <code>service</code> resources for this tenant |
|- | |- | ||
− | | GET || /extensions/{id} || Get a specific <code> | + | | POST || /services || Create a new <code>service</code> resource |
+ | |- | ||
+ | | GET || /services/{id} || Get a specific <code>service</code> resource | ||
+ | |- | ||
+ | | PUT || /services/{id} || Update a complete <code>service</code> resource | ||
+ | |- | ||
+ | | PATCH || /services/{id} || Update select attributes of an <code>service</code> resource | ||
+ | |- | ||
+ | | DELETE || /services/{id} || Delete this <code>service</code> resource. | ||
+ | |} | ||
+ | {| class="wikitable" | ||
+ | | GET || /extensions || Get a list of the <code>extension</code> resources for this tenant | ||
+ | |- | ||
+ | | GET || /extensions/{id} || Get a specific <code>extension</code> resource | ||
|} | |} | ||
Line 67: | Line 80: | ||
The individual customer that uses the hosted Platform. | The individual customer that uses the hosted Platform. | ||
− | ==== | + | ==== platform ==== |
− | The <code> | + | The <code>platform</code> resource is the root level resource that refers to all the other resources owned by this tenant. The purpose of this resource is to provide API introspection. |
+ | |||
+ | ==== assembly ==== | ||
+ | The <code>assembly</code> resource represents a group of components that make up a running instance of an application. You may casually refer to this as "the application" but we refer to it as an assembly because most cloud applications are actually a system of multiple service instances that make up a system. For example, a three-tier web application may have a load balancer component, a group of application servers, and a database server all represented as <code>component</code> resources that make up an <code>assembly</code> resource. An <code>assembly</code> resource has at least one <code>component</code> resource associated with it. | ||
+ | |||
+ | ==== plan ==== | ||
+ | Plan resources are used to create <code>assembly</code> resources. A <code>plan</code> resource may be used repeatedly to create an arbitrary number of <code>assembly</code> instances. It's possible for us to skip the concept of a <code>plan</code> completely, and just use <code>assemblies</code>, and pass in Plan files. That would just make the creation of additional <code>assemblies</code> a bit slower which might be annoying in use cases where you really want to make a whole bunch of them, or you want them to spin up really fast. | ||
− | ==== | + | ==== component ==== |
− | The <code> | + | The <code>component</code> resource represents one part of an <code>assembly</code> needed by your application. For example, an instance of a database service may be a <code>component</code>. A <code>component</code> resource may also represent a static artifact, such as an archive file that contains data for initializing your application. An <code>assembly</code> may have different components that represent different processes that run. For example, you may have one <code>component</code> that represents an API service process, and another that represents a web UI process that consumes that API service. This simplest case is when an <code>assembly</code> has only one component. For examaple your component may be named "PHP" and refers to the PHP <code>service</code> offered by the platform for running a PHP application. |
− | |||
− | |||
− | ==== | + | ==== service ==== |
− | The <code> | + | The <code>service</code> resource represents a networked service provided by a <code>Platform</code> Provider. You may create <code>component</code> resources that refer to <code>service</code> resources. The <code>component</code> represents an instance of the <code>service</code>. Your application may use that service remotely over the network, and the <code>component</code> is how it gets clues about how to connect to it, such as attributes defining a connection URL. In this usage, the <code>component</code> is a virtual representation of a service provided elsewhere (by another application, or by a <code>Platform</code> Provider). For example, the <code>Platform</code> may offer a default <code>service</code> named "mysql". You may create multiple <code>component</code> resources that reference different instances of the "mysql" service. Each <code>component</code> may represent a multi-tenant instance of a MySQL database (perhaps a logical database) service offered by the Platform for a given <code>assembly</code>. |
=== Advanced === | === Advanced === | ||
− | ==== | + | ==== extension ==== |
− | The <code> | + | The <code>extension</code> resource represents changes that the Provider has added onto a Platform in addition to the ones supplied by Solum by default. This may include additional protocol semantics, resource types, application lifecycle states, etc. Anything may be added, as long as it does not contradict the base functionality offered by Solum. |
− | ==== | + | ==== operation ==== |
− | The <code> | + | The <code>operation</code> resource represents an action that can be taken on a resource. operations can be added to <code>assembly</code>, <code>component</code>, or <code>service</code> resources. |
− | ==== | + | ==== sensor ==== |
− | The <code> | + | The <code>sensor</code> resource represents an dynamic data that can be collected from a resource. For example, statistics about the access rate of a resource (usually a <code>component</code>). A <code>sensor</code> resource can be added to <code>assembly</code>, <code>component</code>, or <code>service</code> resources. |
== Types == | == Types == | ||
Line 98: | Line 115: | ||
{ | { | ||
"href": URI, | "href": URI, | ||
− | " | + | "target_name": String |
} | } | ||
The following attributes are present in a Link. Other attributes, not defined in this specification, may also be present. | The following attributes are present in a Link. Other attributes, not defined in this specification, may also be present. | ||
==== href ==== | ==== href ==== | ||
This attribute is the URI [[http://www.ietf.org/rfc/rfc3986.txt RFC3986]] of the resource referenced by this Link. The value of this attribute may be changed by the Provider. Consumers may not change the value of this attribute. | This attribute is the URI [[http://www.ietf.org/rfc/rfc3986.txt RFC3986]] of the resource referenced by this Link. The value of this attribute may be changed by the Provider. Consumers may not change the value of this attribute. | ||
− | ==== | + | ==== target_name ==== |
This attribute echoes the value of the “name” attribute of the resource referenced by this Link. The value of this attribute may be changed by the Platform. Consumers may not change the value of this attribute. | This attribute echoes the value of the “name” attribute of the resource referenced by this Link. The value of this attribute may be changed by the Platform. Consumers may not change the value of this attribute. | ||
Line 122: | Line 139: | ||
"type": "platform", | "type": "platform", | ||
"description": String ?, | "description": String ?, | ||
− | " | + | "extensions_uri": "/extensions", |
− | " | + | "implementation_version": String ?, |
"assemblies": Link[] ?, | "assemblies": Link[] ?, | ||
"components": Link[] ?, | "components": Link[] ?, | ||
"services": Link[] ?, | "services": Link[] ?, | ||
− | " | + | "parameter_definitions_uri": URI |
} | } | ||
− | === | + | === assembly === |
− | The <code> | + | The <code>assembly</code> resource represents a group of components that make up a running instance of an application. You may casually refer to this as "the application" but we refer to it as an <code>assembly</code> because most cloud applications are actually a system of multiple service instances that make up a system. For example, a three-tier web application may have a load balancer component, a group of application servers, and a database server all represented as <code>component</code> resources that make up an <code>assembly</code> resource. An <code>assembly</code> resource has at least one <code>component</code> resource associated with it. |
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Verb !! URI !! Description | ! Verb !! URI !! Description | ||
|- | |- | ||
− | | GET || /assemblies || Get a list of the <code> | + | | GET || /assemblies || Get a list of the <code>assembly</code> resources for this tenant |
|- | |- | ||
− | | POST || /assemblies || Create a new <code> | + | | POST || /assemblies || Create a new <code>assembly</code> resource |
|- | |- | ||
− | | GET || /assemblies/{id} || Get a specific <code> | + | | GET || /assemblies/{id} || Get a specific <code>assembly</code> resource |
|- | |- | ||
− | | PUT || /assemblies/{id} || Update a complete <code> | + | | PUT || /assemblies/{id} || Update a complete <code>assembly</code> resource |
|- | |- | ||
− | | PATCH || /assemblies/{id} || Update select attributes of an <code> | + | | PATCH || /assemblies/{id} || Update select attributes of an <code>assembly</code> resource |
|- | |- | ||
− | | DELETE || /assemblies/{id} || Delete this <code> | + | | DELETE || /assemblies/{id} || Delete this <code>assembly</code> resource. |
|} | |} | ||
{ | { | ||
Line 153: | Line 170: | ||
"type": "assembly", | "type": "assembly", | ||
"description": String ?, | "description": String ?, | ||
− | " | + | "components": Link[] ?, |
− | " | + | "operations_uri": URI ?, |
− | " | + | "sensors_uri": URI ? |
+ | } | ||
+ | |||
+ | === plan === | ||
+ | The </code>plan</code> resource is used to create <code>assembly</code> resources. A <code>plan</code> resource may be used repeatedly to create an arbitrary number of <code>assembly</code> instances. It's possible for us to skip the concept of a <code>plan</code> completely, and just use <code>assemblies</code>, and pass in Plan files. That would just make the creation of additional <code>assemblies</code> a bit slower which might be annoying in use cases where you really want to make a whole bunch of them, or you want them to spin up really fast. | ||
+ | |||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! Verb !! URI !! Description | ||
+ | |- | ||
+ | | GET || /plans || Get a list of the <code>plan</code> resources for this tenant | ||
+ | |- | ||
+ | | POST || /plans || Create a new <code>plan</code> resource | ||
+ | |- | ||
+ | | GET || /plans/{id} || Get a specific <code>plan</code> resource | ||
+ | |- | ||
+ | | PUT || /plans/{id} || Update a complete <code>plan</code> resource | ||
+ | |- | ||
+ | | PATCH || /plans/{id} || Update select attributes of an <code>plan</code> resource | ||
+ | |- | ||
+ | | DELETE || /plans/{id} || Delete this <code>plan</code> resource. | ||
+ | |} | ||
+ | { | ||
+ | "name": String ? | ||
+ | "description": String ? | ||
+ | "tags": String[] ? | ||
+ | "camp_version": String | ||
+ | "origin": String ? | ||
+ | "artifacts": ArtifactSpecification[] ? | ||
+ | "services": ServiceSpecification[] ? | ||
} | } | ||
− | === | + | === component === |
− | The <code> | + | The <code>component</code> resource represents one part of an <code>assembly</code> needed by your application. For example, an instance of a database service may be a <code>component</code>. A <code>component</code> resource may also represent a static artifact, such as an archive file that contains data for initializing your application. An <code>assembly</code> may have different components that represent different processes that run. For example, you may have one <code>component</code> that represents an API service process, and another that represents a web UI process that consumes that API service. This simplest case is when an <code>assembly</code> has only one component. For exmaple your component may be named "PHP" and refers to the PHP <code>service</code> offered by the platform for running a PHP application. |
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Verb !! URI !! Description | ! Verb !! URI !! Description | ||
|- | |- | ||
− | | GET || /components || Get a list of the <code> | + | | GET || /components || Get a list of the <code>component</code> resources for this tenant |
|- | |- | ||
− | | POST || /components || Create a new <code> | + | | POST || /components || Create a new <code>component</code> resource |
|- | |- | ||
− | | GET || /components/{id} || Get a specific <code> | + | | GET || /components/{id} || Get a specific <code>component</code> resource |
|- | |- | ||
− | | PUT || /components/{id} || Update a complete <code> | + | | PUT || /components/{id} || Update a complete <code>component</code> resource |
|- | |- | ||
− | | PATCH || /components/{id} || Update select attributes of an <code> | + | | PATCH || /components/{id} || Update select attributes of an <code>component</code> resource |
|- | |- | ||
− | | DELETE || /components/{id} || Delete this <code> | + | | DELETE || /components/{id} || Delete this <code>component</code> resource. |
|} | |} | ||
{ | { | ||
Line 185: | Line 231: | ||
"components": Link[] ?, | "components": Link[] ?, | ||
"services": Link[] ?, | "services": Link[] ?, | ||
− | " | + | "operations_uri": URI ?, |
− | " | + | "sensors_uri": URI ? |
} | } | ||
− | === | + | === service === |
− | The <code> | + | The <code>service</code> resource represents a networked service provided by a <code>Platform</code> Provider. You may create <code>component</code> resources that refer to <code>service</code> resources. The <code>component</code> represents an instance of the <code>service</code>. Your application connects to the component that using a network protocol. For example, the <code>Platform</code> may offer a default <code>service</code> named "mysql". You may create multiple <code>component</code> resources that reference different instances of the "mysql" service. Each <code>component</code> may be a multi-tenant instance of a MySQL database (perhaps a logical database) service offered by the Platform for a given <code>assembly</code>. |
− | ==== | + | ==== services resource ==== |
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Verb !! URI !! Description | ! Verb !! URI !! Description | ||
|- | |- | ||
− | | GET || /services || Get a list of the <code> | + | | GET || /services || Get a list of the <code>service</code> resources for this tenant |
|- | |- | ||
− | | POST || /services || Create a new <code> | + | | POST || /services || Create a new <code>service</code> resource |
|} | |} | ||
Plural representation (list): | Plural representation (list): | ||
Line 208: | Line 254: | ||
"type": "services", | "type": "services", | ||
"description": String, ? | "description": String, ? | ||
− | " | + | "service_links": Link[] |
} | } | ||
− | ==== | + | ==== service resource ==== |
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
− | | GET || /services/{id} || Get a specific <code> | + | | GET || /services/{id} || Get a specific <code>service</code> resource |
|- | |- | ||
− | | PUT || /services/{id} || Update a complete <code> | + | | PUT || /services/{id} || Update a complete <code>service</code> resource (subject to access control rules) |
|- | |- | ||
− | | PATCH || /services/{id} || Update select attributes of an <code> | + | | PATCH || /services/{id} || Update select attributes of an <code>service</code> resource (subject to access control rules) |
|- | |- | ||
− | | DELETE || /services/{id} || Delete this <code> | + | | DELETE || /services/{id} || Delete this <code>service</code> resource. (subject to access control rules) |
|} | |} | ||
Singular representation: | Singular representation: | ||
Line 230: | Line 276: | ||
"description": String ?, | "description": String ?, | ||
"tags": String[] ?, | "tags": String[] ?, | ||
− | " | + | "operations_uri": URI ?, |
− | " | + | "sensors_uri": URI ?, |
− | " | + | "read_only": Boolean |
} | } | ||
− | Note: Solum prohibits PUT, PATCH, and DELETE calls on the | + | Note: Solum prohibits PUT, PATCH, and DELETE calls on the </code>services</code> provided as part of the base configuration offered by the Provider. In this case the readOnly attribute will be set to TRUE. Any <code>service</code> resourcess added by a tenant will have a readOnly attribute set to FALSE, and may be modified or deleted by that same tenant. |
− | === | + | === extension === |
− | The <code> | + | The <code>extension</code> resource represents changes that the Provider has added onto a Platform in addition to the ones supplied by Solum by default. This may include additional protocol semantics, resource types, application lifecycle states, resource attributes, etc. Anything may be added, as long as it does not contradict the base functionality offered by Solum. |
− | ==== | + | ==== extensions resource ==== |
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Verb !! URI !! Description | ! Verb !! URI !! Description | ||
|- | |- | ||
− | | GET || /extensions || Get a list of the <code> | + | | GET || /extensions || Get a list of the <code>extension</code> resources for this tenant |
|} | |} | ||
Plural representation (list): | Plural representation (list): | ||
Line 251: | Line 297: | ||
"type": "extensions", | "type": "extensions", | ||
"description": String, ? | "description": String, ? | ||
− | " | + | "extension_links": Link[] |
} | } | ||
− | ==== | + | ==== extension resource ==== |
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Verb !! URI !! Description | ! Verb !! URI !! Description | ||
|- | |- | ||
− | | GET || /extensions/{id} || Get a specific <code> | + | | GET || /extensions/{id} || Get a specific <code>extension</code> resource |
|} | |} | ||
Singular representation: | Singular representation: | ||
Line 270: | Line 316: | ||
} | } | ||
− | === | + | === operation === |
− | An <code> | + | An <code>operation</code> resource represents an operation or action available on a target resource. This is for defining actions that may change the state of the resource they are related to. For example, the API already provides ways to register, start, and stop your application (POST an <code>assembly</code> to register+start, and DELETE an <code>assembly</code> to stop) but operations provide a way to extend the system to add your own actions such as "pause" and "resume", or "scale_up" and "scale_down". It has the following representation: |
− | ==== | + | ==== operations resource ==== |
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Verb !! URI !! Description | ! Verb !! URI !! Description | ||
|- | |- | ||
− | | GET || /operations || Get a list of the <code> | + | | GET || /operations || Get a list of the <code>operation</code> resources for this tenant |
|- | |- | ||
− | | POST || /operations || Create a new <code> | + | | POST || /operations || Create a new <code>operation</code> resource |
|} | |} | ||
The plural representation (list): | The plural representation (list): | ||
Line 289: | Line 335: | ||
"type": "operations", | "type": "operations", | ||
"description": String ?, | "description": String ?, | ||
− | " | + | "target_resource": URI, |
− | " | + | "operation_links": Link[] |
} | } | ||
− | ==== | + | ==== operation resource ==== |
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Verb !! URI !! Description | ! Verb !! URI !! Description | ||
|- | |- | ||
− | | GET || /operations/{id} || Get a specific <code> | + | | GET || /operations/{id} || Get a specific <code>operation</code> resource |
|- | |- | ||
− | | PUT || /operations/{id} || Update a complete <code> | + | | PUT || /operations/{id} || Update a complete <code>operation</code> resource |
|- | |- | ||
− | | PATCH || /operations/{id} || Update an attribute of an <code> | + | | PATCH || /operations/{id} || Update an attribute of an <code>operation</code> resource |
|- | |- | ||
− | | DELETE || /operations/{id} || Delete a specific <code> | + | | DELETE || /operations/{id} || Delete a specific <code>operation</code> resource |
|} | |} | ||
The singular representation: | The singular representation: | ||
Line 318: | Line 364: | ||
Note that the <code>documentation</code> attribute is a link to (probably a PDF) document that explains the semantics of the operation you are defining. This is a lightweight method of allowing the API to be extensible without requiring a markup language. | Note that the <code>documentation</code> attribute is a link to (probably a PDF) document that explains the semantics of the operation you are defining. This is a lightweight method of allowing the API to be extensible without requiring a markup language. | ||
− | === | + | === sensor === |
− | A <code> | + | A <code>sensor</code> resource represents exactly one supported sensor on one or more resources. <code>sensor</code> resources represent dynamic data about resources, such as metrics or state. <code>sensor</code> resources are useful for exposing data that changes rapidly, or that may need to be fetched from a secondary system. It has the following representation: |
− | ==== | + | ==== sensors resource ==== |
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Verb !! URI !! Description | ! Verb !! URI !! Description | ||
|- | |- | ||
− | | GET || /sensors || Get a a list of <code> | + | | GET || /sensors || Get a a list of <code>sensor</code> resources for this tenant |
|- | |- | ||
− | | POST || /sensors || Create a new <code> | + | | POST || /sensors || Create a new <code>sensor</code> resource |
|} | |} | ||
The plural representation (list): | The plural representation (list): | ||
Line 337: | Line 383: | ||
"type": "sensors", | "type": "sensors", | ||
"description": String ?, | "description": String ?, | ||
− | " | + | "target_resource": URI, |
− | " | + | "sensor_links": Link[] |
} | } | ||
− | ==== | + | ==== sensor resource ==== |
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Verb !! URI !! Description | ! Verb !! URI !! Description | ||
|- | |- | ||
− | | GET || /sensors/{id} || Get a specific <code> | + | | GET || /sensors/{id} || Get a specific <code>sensor</code> resource |
|- | |- | ||
− | | PUT || /sensors/{id} || Update a complete <code> | + | | PUT || /sensors/{id} || Update a complete <code>sensor</code> resource |
|- | |- | ||
− | | PATCH || /sensors/{id} || Update an attribute of an <code> | + | | PATCH || /sensors/{id} || Update an attribute of an <code>sensor</code> resource |
|- | |- | ||
− | | DELETE || /sensors/{id} || Delete a specific <code> | + | | DELETE || /sensors/{id} || Delete a specific <code>sensor</code> resource |
|} | |} | ||
The singular representation: | The singular representation: | ||
Line 362: | Line 408: | ||
"description": String ?, | "description": String ?, | ||
"documentation": URI, | "documentation": URI, | ||
− | " | + | "target_resource": URI, |
− | " | + | "sensor_type": String, |
− | "value": < | + | "value": <sensor_type> ?, |
"timestamp": Timestamp ?, | "timestamp": Timestamp ?, | ||
− | " | + | "operations_uri": URI ? |
} | } |
Revision as of 07:28, 17 December 2013
Blueprint: https://blueprints.launchpad.net/solum/+spec/api
Proposed By: Adrian Otto
Review comments here: https://etherpad.openstack.org/p/solum-api-spec-review
Contents
API
Synopsis
Verb | URI | Description |
---|---|---|
GET | / | Get the root Platform resource
|
GET | /assemblies | Get a list of the assembly resources for this tenant
|
POST | /assemblies | Create a new assembly resource
|
GET | /assemblies/{id} | Get a specific assembly resource
|
PUT | /assemblies/{id} | Update a complete assembly resource
|
PATCH | /assemblies/{id} | Update select attributes of an assembly resource
|
DELETE | /assemblies/{id} | Delete this assembly resource.
|
GET | /plans | Get a list of the plan resources for this tenant
|
POST | /plans | Create a new plan resource
|
GET | /plans/{id} | Get a specific plan resource
|
PUT | /plans/{id} | Update a complete plan resource
|
PATCH | /plans/{id} | Update select attributes of a plan resource
|
DELETE | /plans/{id} | Delete this plan resource.
|
GET | /components | Get a list of the component resources for this tenant
|
POST | /components | Create a new component resource
|
GET | /components/{id} | Get a specific component resource
|
PUT | /components/{id} | Update a complete component resource
|
PATCH | /components/{id} | Update select attributes of an component resource
|
DELETE | /components/{id} | Delete this component resource.
|
GET | /services | Get a list of the service resources for this tenant
|
POST | /services | Create a new service resource
|
GET | /services/{id} | Get a specific service resource
|
PUT | /services/{id} | Update a complete service resource
|
PATCH | /services/{id} | Update select attributes of an service resource
|
DELETE | /services/{id} | Delete this service resource.
|
GET | /extensions | Get a list of the extension resources for this tenant
|
GET | /extensions/{id} | Get a specific extension resource
|
API Concepts
This section provides an overview of the different aspects of the API, and what they represent. See also: Definitions with a conceptual diagram.
Basics
Roles
Provider
The organization offering hosted platform services to its customers.
Consumer
The individual customer that uses the hosted Platform.
platform
The platform
resource is the root level resource that refers to all the other resources owned by this tenant. The purpose of this resource is to provide API introspection.
assembly
The assembly
resource represents a group of components that make up a running instance of an application. You may casually refer to this as "the application" but we refer to it as an assembly because most cloud applications are actually a system of multiple service instances that make up a system. For example, a three-tier web application may have a load balancer component, a group of application servers, and a database server all represented as component
resources that make up an assembly
resource. An assembly
resource has at least one component
resource associated with it.
plan
Plan resources are used to create assembly
resources. A plan
resource may be used repeatedly to create an arbitrary number of assembly
instances. It's possible for us to skip the concept of a plan
completely, and just use assemblies
, and pass in Plan files. That would just make the creation of additional assemblies
a bit slower which might be annoying in use cases where you really want to make a whole bunch of them, or you want them to spin up really fast.
component
The component
resource represents one part of an assembly
needed by your application. For example, an instance of a database service may be a component
. A component
resource may also represent a static artifact, such as an archive file that contains data for initializing your application. An assembly
may have different components that represent different processes that run. For example, you may have one component
that represents an API service process, and another that represents a web UI process that consumes that API service. This simplest case is when an assembly
has only one component. For examaple your component may be named "PHP" and refers to the PHP service
offered by the platform for running a PHP application.
service
The service
resource represents a networked service provided by a Platform
Provider. You may create component
resources that refer to service
resources. The component
represents an instance of the service
. Your application may use that service remotely over the network, and the component
is how it gets clues about how to connect to it, such as attributes defining a connection URL. In this usage, the component
is a virtual representation of a service provided elsewhere (by another application, or by a Platform
Provider). For example, the Platform
may offer a default service
named "mysql". You may create multiple component
resources that reference different instances of the "mysql" service. Each component
may represent a multi-tenant instance of a MySQL database (perhaps a logical database) service offered by the Platform for a given assembly
.
Advanced
extension
The extension
resource represents changes that the Provider has added onto a Platform in addition to the ones supplied by Solum by default. This may include additional protocol semantics, resource types, application lifecycle states, etc. Anything may be added, as long as it does not contradict the base functionality offered by Solum.
operation
The operation
resource represents an action that can be taken on a resource. operations can be added to assembly
, component
, or service
resources.
sensor
The sensor
resource represents an dynamic data that can be collected from a resource. For example, statistics about the access rate of a resource (usually a component
). A sensor
resource can be added to assembly
, component
, or service
resources.
Types
This section details the different data types used by the API.
Boolean
As defined by JSON [RFC4627], a token having a literal value of either true or false.
String
A UNICODE string as defined by JSON [RFC4627].
URI
A String (see above) that conforms to the syntax defined in [RFC3986].
Link
Relation used for a resource entity has attribute values that link to other resource entities. For example, a Platform resource entity attribute values points to assemblies. The “Link” type defined here is used for such attribute values. It is typically only used as an array of Link entities.
{ "href": URI, "target_name": String }
The following attributes are present in a Link. Other attributes, not defined in this specification, may also be present.
href
This attribute is the URI [RFC3986] of the resource referenced by this Link. The value of this attribute may be changed by the Provider. Consumers may not change the value of this attribute.
target_name
This attribute echoes the value of the “name” attribute of the resource referenced by this Link. The value of this attribute may be changed by the Platform. Consumers may not change the value of this attribute.
Protocol and Resource Representations
This section shows the representation of each of the resources in JSON format, and how you interact with them through the REST API. Note: The Link[] type indicates an array of Links. A "?" character indicates the attribute is optional.
Platform
The Platform
resource is the root level resource that refers to all the other resources owned by this tenant. The purpose of the Platform
resource is for API introspection.
Verb | URI | Description |
---|---|---|
GET | / | Get the root Platform resource
|
{ "uri": URI, "name": String, "type": "platform", "description": String ?, "extensions_uri": "/extensions", "implementation_version": String ?, "assemblies": Link[] ?, "components": Link[] ?, "services": Link[] ?, "parameter_definitions_uri": URI }
assembly
The assembly
resource represents a group of components that make up a running instance of an application. You may casually refer to this as "the application" but we refer to it as an assembly
because most cloud applications are actually a system of multiple service instances that make up a system. For example, a three-tier web application may have a load balancer component, a group of application servers, and a database server all represented as component
resources that make up an assembly
resource. An assembly
resource has at least one component
resource associated with it.
Verb | URI | Description |
---|---|---|
GET | /assemblies | Get a list of the assembly resources for this tenant
|
POST | /assemblies | Create a new assembly resource
|
GET | /assemblies/{id} | Get a specific assembly resource
|
PUT | /assemblies/{id} | Update a complete assembly resource
|
PATCH | /assemblies/{id} | Update select attributes of an assembly resource
|
DELETE | /assemblies/{id} | Delete this assembly resource.
|
{ "uri": URI, "name": String, "type": "assembly", "description": String ?, "components": Link[] ?, "operations_uri": URI ?, "sensors_uri": URI ? }
plan
The </code>plan</code> resource is used to create assembly
resources. A plan
resource may be used repeatedly to create an arbitrary number of assembly
instances. It's possible for us to skip the concept of a plan
completely, and just use assemblies
, and pass in Plan files. That would just make the creation of additional assemblies
a bit slower which might be annoying in use cases where you really want to make a whole bunch of them, or you want them to spin up really fast.
Verb | URI | Description |
---|---|---|
GET | /plans | Get a list of the plan resources for this tenant
|
POST | /plans | Create a new plan resource
|
GET | /plans/{id} | Get a specific plan resource
|
PUT | /plans/{id} | Update a complete plan resource
|
PATCH | /plans/{id} | Update select attributes of an plan resource
|
DELETE | /plans/{id} | Delete this plan resource.
|
{ "name": String ? "description": String ? "tags": String[] ? "camp_version": String "origin": String ? "artifacts": ArtifactSpecification[] ? "services": ServiceSpecification[] ? }
component
The component
resource represents one part of an assembly
needed by your application. For example, an instance of a database service may be a component
. A component
resource may also represent a static artifact, such as an archive file that contains data for initializing your application. An assembly
may have different components that represent different processes that run. For example, you may have one component
that represents an API service process, and another that represents a web UI process that consumes that API service. This simplest case is when an assembly
has only one component. For exmaple your component may be named "PHP" and refers to the PHP service
offered by the platform for running a PHP application.
Verb | URI | Description |
---|---|---|
GET | /components | Get a list of the component resources for this tenant
|
POST | /components | Create a new component resource
|
GET | /components/{id} | Get a specific component resource
|
PUT | /components/{id} | Update a complete component resource
|
PATCH | /components/{id} | Update select attributes of an component resource
|
DELETE | /components/{id} | Delete this component resource.
|
{ "uri": URI, "name": String, "type": "component", "description": String ?, "tags": String[] ?, "assembly": Link, "components": Link[] ?, "services": Link[] ?, "operations_uri": URI ?, "sensors_uri": URI ? }
service
The service
resource represents a networked service provided by a Platform
Provider. You may create component
resources that refer to service
resources. The component
represents an instance of the service
. Your application connects to the component that using a network protocol. For example, the Platform
may offer a default service
named "mysql". You may create multiple component
resources that reference different instances of the "mysql" service. Each component
may be a multi-tenant instance of a MySQL database (perhaps a logical database) service offered by the Platform for a given assembly
.
services resource
Verb | URI | Description |
---|---|---|
GET | /services | Get a list of the service resources for this tenant
|
POST | /services | Create a new service resource
|
Plural representation (list):
Request: GET /services ... Response: { "uri": URI, "name": String, "type": "services", "description": String, ? "service_links": Link[] }
service resource
GET | /services/{id} | Get a specific service resource
|
PUT | /services/{id} | Update a complete service resource (subject to access control rules)
|
PATCH | /services/{id} | Update select attributes of an service resource (subject to access control rules)
|
DELETE | /services/{id} | Delete this service resource. (subject to access control rules)
|
Singular representation:
Request: GET /service/{id} ... Response: { "uri": URI, "name": String, "type": "service", "description": String ?, "tags": String[] ?, "operations_uri": URI ?, "sensors_uri": URI ?, "read_only": Boolean }
Note: Solum prohibits PUT, PATCH, and DELETE calls on the </code>services</code> provided as part of the base configuration offered by the Provider. In this case the readOnly attribute will be set to TRUE. Any service
resourcess added by a tenant will have a readOnly attribute set to FALSE, and may be modified or deleted by that same tenant.
extension
The extension
resource represents changes that the Provider has added onto a Platform in addition to the ones supplied by Solum by default. This may include additional protocol semantics, resource types, application lifecycle states, resource attributes, etc. Anything may be added, as long as it does not contradict the base functionality offered by Solum.
extensions resource
Verb | URI | Description |
---|---|---|
GET | /extensions | Get a list of the extension resources for this tenant
|
Plural representation (list):
{ "uri": URI, "name": String, "type": "extensions", "description": String, ? "extension_links": Link[] }
extension resource
Verb | URI | Description |
---|---|---|
GET | /extensions/{id} | Get a specific extension resource
|
Singular representation:
{ "uri": URI, "name": String, "type": "extension", "description": String, "version": String, "documentation": URI ? }
operation
An operation
resource represents an operation or action available on a target resource. This is for defining actions that may change the state of the resource they are related to. For example, the API already provides ways to register, start, and stop your application (POST an assembly
to register+start, and DELETE an assembly
to stop) but operations provide a way to extend the system to add your own actions such as "pause" and "resume", or "scale_up" and "scale_down". It has the following representation:
operations resource
Verb | URI | Description |
---|---|---|
GET | /operations | Get a list of the operation resources for this tenant
|
POST | /operations | Create a new operation resource
|
The plural representation (list):
Request: GET /operations ... Response: { "uri": URI, "name": String, "type": "operations", "description": String ?, "target_resource": URI, "operation_links": Link[] }
operation resource
Verb | URI | Description |
---|---|---|
GET | /operations/{id} | Get a specific operation resource
|
PUT | /operations/{id} | Update a complete operation resource
|
PATCH | /operations/{id} | Update an attribute of an operation resource
|
DELETE | /operations/{id} | Delete a specific operation resource
|
The singular representation:
Request: GET /operations/{id} ... Response: { "uri": URI, "name": String, "type": "operation", "description": String ?, "documentation": URI, "targetResource": URI }
Note that the documentation
attribute is a link to (probably a PDF) document that explains the semantics of the operation you are defining. This is a lightweight method of allowing the API to be extensible without requiring a markup language.
sensor
A sensor
resource represents exactly one supported sensor on one or more resources. sensor
resources represent dynamic data about resources, such as metrics or state. sensor
resources are useful for exposing data that changes rapidly, or that may need to be fetched from a secondary system. It has the following representation:
sensors resource
Verb | URI | Description |
---|---|---|
GET | /sensors | Get a a list of sensor resources for this tenant
|
POST | /sensors | Create a new sensor resource
|
The plural representation (list):
Request: GET /sensors ... Response: { "uri": URI, "name": String, "type": "sensors", "description": String ?, "target_resource": URI, "sensor_links": Link[] }
sensor resource
Verb | URI | Description |
---|---|---|
GET | /sensors/{id} | Get a specific sensor resource
|
PUT | /sensors/{id} | Update a complete sensor resource
|
PATCH | /sensors/{id} | Update an attribute of an sensor resource
|
DELETE | /sensors/{id} | Delete a specific sensor resource
|
The singular representation:
Request: GET /sensors/{id} ... Response: { "uri": URI, "name": String, "type": "sensor", "description": String ?, "documentation": URI, "target_resource": URI, "sensor_type": String, "value": <sensor_type> ?, "timestamp": Timestamp ?, "operations_uri": URI ? }