Jump to: navigation, search

Difference between revisions of "Solum/API"

m
(Array)
 
(9 intermediate revisions by 3 users not shown)
Line 2: Line 2:
  
 
Proposed By: Adrian Otto
 
Proposed By: Adrian Otto
 +
 
Review comments here: https://etherpad.openstack.org/p/solum-api-spec-review
 
Review comments here: https://etherpad.openstack.org/p/solum-api-spec-review
  
Line 13: Line 14:
 
|}
 
|}
 
{| class="wikitable"
 
{| class="wikitable"
| GET || /assemblies || Get a list of the <code>Assembly</code> resources for this tenant
+
| GET || /assemblies || Get a list of the <code>assembly</code> resources for this tenant
 +
|-
 +
| POST || /assemblies || Create a new <code>assembly</code> resource
 +
|-
 +
| GET || /assemblies/{id} || Get a specific <code>assembly</code> resource
 +
|-
 +
| PUT || /assemblies/{id} || Update a complete <code>assembly</code> resource
 +
|-
 +
| PATCH || /assemblies/{id} || Update select attributes of an <code>assembly</code> resource
 +
|-
 +
| DELETE || /assemblies/{id} || Delete this <code>assembly</code> resource.
 +
|}
 +
{| class="wikitable"
 +
| GET || /plans || Get a list of the <code>plan</code> resources for this tenant
 
|-
 
|-
| POST || /assemblies || Create a new <code>Assembly</code> resource
+
| POST || /plans || Create a new <code>plan</code> resource
 
|-
 
|-
| GET || /assemblies/{id} || Get a specific <code>Assembly</code> resource
+
| GET || /plans/{id} || Get a specific <code>plan</code> resource
 
|-
 
|-
| PUT || /assemblies/{id} || Update a complete <code>Assembly</code> resource
+
| PUT || /plans/{id} || Update a complete <code>plan</code> resource
 
|-
 
|-
| PATCH || /assemblies/{id} || Update select attributes of an <code>Assembly</code> resource
+
| PATCH || /plans/{id} || Update select attributes of a <code>plan</code> resource
 
|-
 
|-
| DELETE || /assemblies/{id} || Delete this <code>Assembly</code> resource.
+
| DELETE || /plans/{id} || Delete this <code>plan</code> resource.
 
|}
 
|}
 
{| class="wikitable"
 
{| class="wikitable"
| GET || /components || Get a list of the <code>Component</code> resources for this tenant
+
| GET || /components || Get a list of the <code>component</code> resources for this tenant
 
|-
 
|-
| POST || /components || Create a new <code>Component</code> resource
+
| POST || /components || Create a new <code>component</code> resource
 
|-
 
|-
| GET || /components/{id} || Get a specific <code>Component</code> resource
+
| GET || /components/{id} || Get a specific <code>component</code> resource
 
|-
 
|-
| PUT || /components/{id} || Update a complete <code>Component</code> resource
+
| PUT || /components/{id} || Update a complete <code>component</code> resource
 
|-
 
|-
| PATCH || /components/{id} || Update select attributes of an <code>Component</code> resource
+
| PATCH || /components/{id} || Update select attributes of an <code>component</code> resource
 
|-
 
|-
| DELETE || /components/{id} || Delete this <code>Component</code> resource.
+
| DELETE || /components/{id} || Delete this <code>component</code> resource.
 
|}
 
|}
 
{| class="wikitable"
 
{| class="wikitable"
| GET || /services || Get a list of the <code>Service</code> resources for this tenant
+
| GET || /services || Get a list of the <code>service</code> resources for this tenant
 
|-
 
|-
| POST || /services || Create a new <code>Service</code> resource
+
| POST || /services || Create a new <code>service</code> resource
 
|-
 
|-
| GET || /services/{id} || Get a specific <code>Service</code> resource
+
| GET || /services/{id} || Get a specific <code>service</code> resource
 
|-
 
|-
| PUT || /services/{id} || Update a complete <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
+
| PATCH || /services/{id} || Update select attributes of an <code>service</code> resource
 
|-
 
|-
| DELETE || /services/{id} || Delete this <code>Service</code> resource.
+
| DELETE || /services/{id} || Delete this <code>service</code> resource.
 
|}
 
|}
 
{| class="wikitable"
 
{| class="wikitable"
| GET || /extensions || Get a list of the <code>Extension</code> resources for this tenant
+
| GET || /extensions || Get a list of the <code>extension</code> resources for this tenant
 
|-
 
|-
| GET || /extensions/{id} || Get a specific <code>Extension</code> resource
+
| GET || /extensions/{id} || Get a specific <code>extension</code> resource
 
|}
 
|}
  
Line 66: Line 80:
 
The individual customer that uses the hosted Platform.
 
The individual customer that uses the hosted Platform.
  
==== Platform ====
+
==== platform ====
The <code>Platform</code> resource is the root level resource that refers to all the other resources owned by this tenant.
+
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.
 
==== Component ====
 
The <code>Component</code> resource represents one part of an Assembly 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 Service offered by the platform for running a PHP application.
 
  
==== Service ====
+
==== assembly ====
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 Service 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 Service 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>.
+
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>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>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 ====
+
==== extension ====
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.
+
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 ====
+
==== operation ====
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.
+
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 ====
+
==== sensor ====
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>). Sensors can be added to <code>Assembly</code>, <code>Component</code>, or <code>Service</code> resources.
+
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 ==
 
This section details the different data types used by the API.
 
This section details the different data types used by the API.
 +
=== Array ===
 +
A JSON Array of JSON objects. For example: the pseudocode text "component[]" refers to an array of component resources expressed as JSON objects.
 +
 
=== Boolean ===
 
=== Boolean ===
 
As defined by JSON [[http://www.ietf.org/rfc/rfc4627.txt‎ RFC4627]], a token having a literal value of either true or false.
 
As defined by JSON [[http://www.ietf.org/rfc/rfc4627.txt‎ RFC4627]], a token having a literal value of either true or false.
Line 92: Line 114:
 
=== URI ===
 
=== URI ===
 
A String (see above) that conforms to the syntax defined in [[http://www.ietf.org/rfc/rfc3986.txt RFC3986]].
 
A String (see above) that conforms to the syntax defined in [[http://www.ietf.org/rfc/rfc3986.txt 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,
 
  "targetName": 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 [[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.
 
==== targetName ====
 
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 ==
 
== 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.  
 
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.
+
A "?" character indicates the attribute is optional.
 +
 
 +
# '''No Links'''. We will not use the Link or Link array types that were proposed in the initial API design documentation. Instead we will use inline objects in the serialized output. For example, an assembly, instead of having links to components, would include an array of component resources that are also serialized in the same JSON. Let's refer to the elements of such an array as "inline-listed-resources".
 +
# '''Limited view by default'''. To keep the size of the result set manageable,  we will show only *one* level of detail for inline-listed-resources. If additional detail is required, we can support parameters for showing a configurable depth level, up to a sensible configurable maximum. For example, you might see a list of components as inline-listed-resources, but those listed do not include their own inline-listed-resource lists for additional levels of relations.
 +
# '''Abbreviated Label'''. To indicate that a given inline listed object has additional details that could be queried if that object were loaded using it's URI, we can add an attribute named "abbreviated" that indicates additional fields exist that are not shown in the current view (if it exists and is set to true). This way, if that detail is desired, the object may be accessed individually using its URI, and all the details will be returned.
 +
# '''Pagination'''. To prevent unreasonably large return sets, Solum should have a configurable maximum number if inline listed objects that it will display by default. For example, we may set that limit at 100, in the Solum configuration file, and when the API is queried for an Assembly that contains more than 100 components, that the list of components will be offered as a paginated collection, like an ATOM feed works so that a Next item can be fetched when the last is reached.
 +
 
 
=== Platform ===
 
=== Platform ===
The <code>Platform</code> resource is the root level resource that refers to all the other resources owned by this tenant.
+
The <code>Platform</code> resource is the root level resource that refers to all the other resources owned by this tenant.  The purpose of the <code>Platform</code> resource is for API introspection.
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 120: Line 137:
 
   "type": "platform",
 
   "type": "platform",
 
   "description": String ?,
 
   "description": String ?,
   "extensionsUri": "/extensions",
+
   "extensions_uri": "/extensions",
   "implementationVersion": String ?,
+
   "implementation_version": String ?,
   "assemblies": Link[] ?,
+
   "assemblies": assembly[] ?,
   "components": Link[] ?,
+
   "components": component[] ?,
   "services": Link[] ?,
+
   "services": service[] ?,
   "parameterDefinitionsUri": URI
+
   "parameter_definitions_uri": URI
 
  }
 
  }
  
=== Assembly ===
+
=== 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.  
+
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>Assembly</code> resources for this tenant
+
| GET || /assemblies || Get a list of the <code>assembly</code> resources for this tenant
 
|-
 
|-
| POST || /assemblies || Create a new <code>Assembly</code> resource
+
| POST || /assemblies || Create a new <code>assembly</code> resource
 
|-
 
|-
| GET || /assemblies/{id} || Get a specific <code>Assembly</code> resource
+
| GET || /assemblies/{id} || Get a specific <code>assembly</code> resource
 
|-
 
|-
| PUT || /assemblies/{id} || Update a complete <code>Assembly</code> resource
+
| PUT || /assemblies/{id} || Update a complete <code>assembly</code> resource
 
|-
 
|-
| PATCH || /assemblies/{id} || Update select attributes of an <code>Assembly</code> resource
+
| PATCH || /assemblies/{id} || Update select attributes of an <code>assembly</code> resource
 
|-
 
|-
| DELETE || /assemblies/{id} || Delete this <code>Assembly</code> resource.
+
| DELETE || /assemblies/{id} || Delete this <code>assembly</code> resource.
 
|}
 
|}
 
  {
 
  {
Line 151: Line 168:
 
   "type": "assembly",
 
   "type": "assembly",
 
   "description": String ?,
 
   "description": String ?,
   "Components": Link[] ?,
+
   "components": component[] ?,
   "operationsUri": URI ?,
+
   "operations_uri": URI ?,
   "sensorsUri": URI ?
+
   "sensors_uri": URI ?
 
  }
 
  }
  
=== Component ===
+
=== plan ===
The <code>Component</code> resource represents one part of an Assembly 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 Service offered by the platform for running a PHP application.
+
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[] ?
 +
}
 +
 
 +
Note that the ArtifactSpecification and ServiceSpecification will be detailed in a separate blueprint and specification that describes plan files, which will be used to generate plan resources. That will be linked here upon creation.
 +
 
 +
=== component ===
 +
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>Component</code> resources for this tenant
+
| GET || /components || Get a list of the <code>component</code> resources for this tenant
 
|-
 
|-
| POST || /components || Create a new <code>Component</code> resource
+
| POST || /components || Create a new <code>component</code> resource
 
|-
 
|-
| GET || /components/{id} || Get a specific <code>Component</code> resource
+
| GET || /components/{id} || Get a specific <code>component</code> resource
 
|-
 
|-
| PUT || /components/{id} || Update a complete <code>Component</code> resource
+
| PUT || /components/{id} || Update a complete <code>component</code> resource
 
|-
 
|-
| PATCH || /components/{id} || Update select attributes of an <code>Component</code> resource
+
| PATCH || /components/{id} || Update select attributes of an <code>component</code> resource
 
|-
 
|-
| DELETE || /components/{id} || Delete this <code>Component</code> resource.
+
| DELETE || /components/{id} || Delete this <code>component</code> resource.
 
|}
 
|}
 
  {
 
  {
Line 180: Line 228:
 
   "description": String ?,
 
   "description": String ?,
 
   "tags": String[] ?,
 
   "tags": String[] ?,
   "assembly": Link,
+
   "assembles": assembly[],
   "components": Link[] ?,
+
   "components": component[] ?,
   "services": Link[] ?,
+
   "services": service[] ?,
   "operationsUri": URI ?,
+
   "operations_uri": URI ?,
   "sensorsUri": URI ?
+
   "sensors_uri": URI ?
 
  }
 
  }
  
=== Service ===
+
=== service ===
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 Service 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 Service 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>.
+
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 ====
+
==== services resource ====
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Verb !! URI !! Description
 
! Verb !! URI !! Description
 
|-
 
|-
| GET || /services || Get a list of the <code>Service</code> resources for this tenant
+
| GET || /services || Get a list of the <code>service</code> resources for this tenant
 
|-
 
|-
| POST || /services || Create a new <code>Service</code> resource
+
| POST || /services || Create a new <code>service</code> resource
 
|}
 
|}
 
Plural representation (list):
 
Plural representation (list):
Line 206: Line 254:
 
   "type": "services",
 
   "type": "services",
 
   "description": String, ?
 
   "description": String, ?
   "serviceLinks": Link[]
+
   "services": service[]
 
  }
 
  }
==== Service Resource ====
+
==== service resource ====
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
| GET || /services/{id} || Get a specific <code>Service</code> resource
+
| GET || /services/{id} || Get a specific <code>service</code> resource
 
|-
 
|-
| PUT || /services/{id} || Update a complete <code>Service</code> resource (subject to access control rules)
+
| PUT || /services/{id} || Update a complete <code>service</code> resource (subject to access control rules)
 
|-
 
|-
| PATCH || /services/{id} || Update select attributes of an <code>Service</code> resource (subject to access control rules)
+
| PATCH || /services/{id} || Update select attributes of an <code>service</code> resource (subject to access control rules)
 
|-
 
|-
| DELETE || /services/{id} || Delete this <code>Service</code> resource. (subject to access control rules)
+
| DELETE || /services/{id} || Delete this <code>service</code> resource. (subject to access control rules)
 
|}
 
|}
 
Singular representation:
 
Singular representation:
Line 228: Line 276:
 
   "description": String ?,
 
   "description": String ?,
 
   "tags": String[] ?,
 
   "tags": String[] ?,
   "operationsUri": URI ?,
+
   "operations_uri": URI ?,
   "sensorsUri": URI ?,
+
   "sensors_uri": URI ?,
   "readOnly": Boolean
+
   "read_only": Boolean
 
  }
 
  }
Note: Solum prohibits PUT, PATCH, and DELETE calls on the Services provided as part of the base configuration offered by the Provider. In this case the readOnly attribute will be set to TRUE. Services added by a tenant will have a readOnly attribute set to FALSE, and may be modified or deleted by that same tenant.
+
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 ===
+
=== extension ===
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.
+
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 ====
+
==== extensions resource ====
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Verb !! URI !! Description
 
! Verb !! URI !! Description
 
|-
 
|-
| GET || /extensions || Get a list of the <code>Extension</code> resources for this tenant
+
| GET || /extensions || Get a list of the <code>extension</code> resources for this tenant
 
|}
 
|}
 
Plural representation (list):
 
Plural representation (list):
Line 249: Line 297:
 
   "type": "extensions",
 
   "type": "extensions",
 
   "description": String, ?
 
   "description": String, ?
   "extensionLinks": Link[]
+
   "extensions": extension[]
 
  }
 
  }
==== Extension Resource ====
+
==== extension resource ====
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Verb !! URI !! Description
 
! Verb !! URI !! Description
 
|-
 
|-
| GET || /extensions/{id} || Get a specific <code>Extension</code> resource
+
| GET || /extensions/{id} || Get a specific <code>extension</code> resource
 
|}
 
|}
 
Singular representation:
 
Singular representation:
Line 268: Line 316:
 
  }
 
  }
  
=== Operation ===
+
=== operation ===
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:
+
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 ====
+
==== operations resource ====
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Verb !! URI !! Description
 
! Verb !! URI !! Description
 
|-
 
|-
| GET || /operations || Get a list of the <code>Operation</code> resources for this tenant
+
| GET || /operations || Get a list of the <code>operation</code> resources for this tenant
 
|-
 
|-
| POST || /operations || Create a new <code>Operation</code> resource
+
| POST || /operations || Create a new <code>operation</code> resource
 
|}
 
|}
 
The plural representation (list):
 
The plural representation (list):
Line 287: Line 335:
 
   "type": "operations",
 
   "type": "operations",
 
   "description": String ?,
 
   "description": String ?,
   "targetResource": URI,
+
   "target_resource": URI,
   "operationLinks": Link[]
+
   "operations": operation[]
 
  }
 
  }
==== Operation Resource ====
+
==== operation resource ====
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Verb !! URI !! Description
 
! Verb !! URI !! Description
 
|-
 
|-
| GET || /operations/{id} || Get a specific <code>Operation</code> resource
+
| GET || /operations/{id} || Get a specific <code>operation</code> resource
 
|-
 
|-
| PUT || /operations/{id} || Update a complete <code>Operation</code> resource
+
| PUT || /operations/{id} || Update a complete <code>operation</code> resource
 
|-
 
|-
| PATCH || /operations/{id} || Update an attribute of an <code>Operation</code> resource
+
| PATCH || /operations/{id} || Update an attribute of an <code>operation</code> resource
 
|-
 
|-
| DELETE || /operations/{id} || Delete a specific <code>Operation</code> resource
+
| DELETE || /operations/{id} || Delete a specific <code>operation</code> resource
 
|}
 
|}
 
The singular representation:
 
The singular representation:
Line 316: 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 ===
+
=== sensor ===
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:
+
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 ====
+
==== sensors resource ====
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Verb !! URI !! Description
 
! Verb !! URI !! Description
 
|-
 
|-
| GET || /sensors || Get a a list of <code>Sensor</code> resources for this tenant
+
| GET || /sensors || Get a a list of <code>sensor</code> resources for this tenant
 
|-
 
|-
| POST || /sensors || Create a new <code>Sensor</code> resource
+
| POST || /sensors || Create a new <code>sensor</code> resource
 
|}
 
|}
 
The plural representation (list):
 
The plural representation (list):
Line 335: Line 383:
 
   "type": "sensors",
 
   "type": "sensors",
 
   "description": String ?,
 
   "description": String ?,
   "targetResource": URI,
+
   "target_resource": URI,
   "sensorLinks": Link[]
+
   "sensors": sensor[]
 
  }
 
  }
==== Sensor Resource ====
+
==== sensor resource ====
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Verb !! URI !! Description
 
! Verb !! URI !! Description
 
|-
 
|-
| GET || /sensors/{id} || Get a specific <code>Sensor</code> resource
+
| GET || /sensors/{id} || Get a specific <code>sensor</code> resource
 
|-
 
|-
| PUT || /sensors/{id} || Update a complete <code>Sensor</code> resource
+
| PUT || /sensors/{id} || Update a complete <code>sensor</code> resource
 
|-
 
|-
| PATCH || /sensors/{id} || Update an attribute of an <code>Sensor</code> resource
+
| PATCH || /sensors/{id} || Update an attribute of an <code>sensor</code> resource
 
|-
 
|-
| DELETE || /sensors/{id} || Delete a specific <code>Sensor</code> resource
+
| DELETE || /sensors/{id} || Delete a specific <code>sensor</code> resource
 
|}
 
|}
 
The singular representation:
 
The singular representation:
Line 360: Line 408:
 
   "description": String ?,
 
   "description": String ?,
 
   "documentation": URI,
 
   "documentation": URI,
   "targetResource": URI,
+
   "target_resource": URI,
   "sensorType": String,
+
   "sensor_type": String,
   "value": <sensorType> ?,
+
   "value": <sensor_type> ?,
 
   "timestamp": Timestamp ?,
 
   "timestamp": Timestamp ?,
   "operationsUri": URI ?
+
   "operations_uri": URI ?
 
  }
 
  }

Latest revision as of 22:08, 30 January 2014

Blueprint: https://blueprints.launchpad.net/solum/+spec/api

Proposed By: Adrian Otto

Review comments here: https://etherpad.openstack.org/p/solum-api-spec-review

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.

Array

A JSON Array of JSON objects. For example: the pseudocode text "component[]" refers to an array of component resources expressed as JSON objects.

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].

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. A "?" character indicates the attribute is optional.

  1. No Links. We will not use the Link or Link array types that were proposed in the initial API design documentation. Instead we will use inline objects in the serialized output. For example, an assembly, instead of having links to components, would include an array of component resources that are also serialized in the same JSON. Let's refer to the elements of such an array as "inline-listed-resources".
  2. Limited view by default. To keep the size of the result set manageable, we will show only *one* level of detail for inline-listed-resources. If additional detail is required, we can support parameters for showing a configurable depth level, up to a sensible configurable maximum. For example, you might see a list of components as inline-listed-resources, but those listed do not include their own inline-listed-resource lists for additional levels of relations.
  3. Abbreviated Label. To indicate that a given inline listed object has additional details that could be queried if that object were loaded using it's URI, we can add an attribute named "abbreviated" that indicates additional fields exist that are not shown in the current view (if it exists and is set to true). This way, if that detail is desired, the object may be accessed individually using its URI, and all the details will be returned.
  4. Pagination. To prevent unreasonably large return sets, Solum should have a configurable maximum number if inline listed objects that it will display by default. For example, we may set that limit at 100, in the Solum configuration file, and when the API is queried for an Assembly that contains more than 100 components, that the list of components will be offered as a paginated collection, like an ATOM feed works so that a Next item can be fetched when the last is reached.

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": assembly[] ?,
 "components": component[] ?,
 "services": service[] ?,
 "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": component[] ?,
 "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[] ?
}

Note that the ArtifactSpecification and ServiceSpecification will be detailed in a separate blueprint and specification that describes plan files, which will be used to generate plan resources. That will be linked here upon creation.

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[] ?,
 "assembles": assembly[],
 "components": component[] ?,
 "services": service[] ?,
 "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, ?
 "services": service[]
}

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, ?
 "extensions": extension[]
}

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,
 "operations": operation[]
}

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,
 "sensors": sensor[]
}

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 ?
}