Solum/API

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 =

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.

Provider
The organization offering hosted platform services to its customers.

Consumer
The individual customer that uses the hosted Platform.

platform
The  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  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  resources that make up an   resource. An  resource has at least  one   resource associated with it.

plan
Plan resources are used to create  resources. A  resource may be used repeatedly to create an arbitrary number of   instances. It's possible for us to skip the concept of a  completely, and just use , and pass in Plan files. That would just make the creation of additional  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  resource represents one part of an   needed by your application. For example, an instance of a database service may be a. A  resource may also represent a static artifact, such as an archive file that contains data for initializing your application. An  may have different components that represent different processes that run. For example, you may have one  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  has only one component. For examaple your component may be named "PHP" and refers to the PHP  offered by the platform for running a PHP application.

service
The  resource represents a networked service provided by a   Provider. You may create  resources that refer to   resources. The  represents an instance of the. Your application may use that service remotely over the network, and the  is how it gets clues about how to connect to it, such as attributes defining a connection URL. In this usage, the  is a virtual representation of a service provided elsewhere (by another application, or by a   Provider). For example, the  may offer a default   named "mysql". You may create multiple  resources that reference different instances of the "mysql" service. Each  may represent a multi-tenant instance of a MySQL database (perhaps a logical database) service offered by the Platform for a given.

extension
The  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  resource represents an action that can be taken on a resource. operations can be added to,  , or   resources.

sensor
The  resource represents an dynamic data that can be collected from a resource. For example, statistics about the access rate of a resource (usually a ). A  resource can be added to ,  , or   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  resource is the root level resource that refers to all the other resources owned by this tenant. The purpose of the  resource is for API introspection. { "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  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  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  resources that make up an   resource. An  resource has at least  one   resource associated with it. { "uri": URI, "name": String, "type": "assembly", "description": String ?, "components": component[] ?, "operations_uri": URI ?, "sensors_uri": URI ? }

plan
The plan resource is used to create  resources. A  resource may be used repeatedly to create an arbitrary number of   instances. It's possible for us to skip the concept of a  completely, and just use , and pass in Plan files. That would just make the creation of additional  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.

{ "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  resource represents one part of an   needed by your application. For example, an instance of a database service may be a. A  resource may also represent a static artifact, such as an archive file that contains data for initializing your application. An  may have different components that represent different processes that run. For example, you may have one  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  has only one component. For exmaple your component may be named "PHP" and refers to the PHP  offered by the platform for running a PHP application. { "uri": URI, "name": String, "type": "component", "description": String ?, "tags": String[] ?, "assembles": assembly[], "components": component[] ?, "services": service[] ?, "operations_uri": URI ?, "sensors_uri": URI ? }

service
The  resource represents a networked service provided by a   Provider. You may create  resources that refer to   resources. The  represents an instance of the. Your application connects to the component that using a network protocol. For example, the  may offer a default   named "mysql". You may create multiple  resources that reference different instances of the "mysql" service. Each  may be a multi-tenant instance of a MySQL database (perhaps a logical database) service offered by the Platform for a given.

services resource
Plural representation (list): Request: GET /services ... Response: { "uri": URI, "name": String, "type": "services", "description": String, ? "services": service[] }

service resource
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 services provided as part of the base configuration offered by the Provider. In this case the readOnly attribute will be set to TRUE. Any  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  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
Plural representation (list): { "uri": URI, "name": String, "type": "extensions", "description": String, ? "extensions": extension[] }

extension resource
Singular representation: { "uri": URI, "name": String, "type": "extension", "description": String, "version": String, "documentation": URI ? }

operation
An  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  to register+start, and DELETE an   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
The plural representation (list): Request: GET /operations ... Response: { "uri": URI, "name": String, "type": "operations", "description": String ?, "target_resource": URI, "operations": operation[] }

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  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  resource represents exactly one supported sensor on one or more resources. resources represent dynamic data about resources, such as metrics or state. 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
The plural representation (list): Request: GET /sensors ... Response: { "uri": URI, "name": String, "type": "sensors", "description": String ?, "target_resource": URI, "sensors": sensor[] }

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":  ?, "timestamp": Timestamp ?, "operations_uri": URI ? }