platformdoc/docs/components/component-specification/common-specification.md

   1 # Component specification (Common elements)
   2
   3 This page describes component specification sections that are common (or nearly) to both Docker and CDAP.
   4
   5 ## Component Metadata
   6 Metadata refers to the properties found under the `self` JSON.  This group of properties are used to uniquely identify this component specification and identify the component that this specification is used to capture. The metadata section, represented under `self`, is used to uniquely identify your component among all components in the catalog.
   7
   8 From the specification example above:
   9
  10 ```
  11 "self": {
  12     "version": "1.0.0",
  13     "name": "asimov.component.kpi_anomaly",
  14     "description": "Classifies VNF KPI data as anomalous",
  15     "component_type": "docker"
  16 },
  17 ```
  18
  19 Here is a breakdown of the schema:
  20
  21 Property Name | Type | Description
  22 ------------- | ---- | -----------
  23 version | string | *Required*.  Semantic version for this specification
  24 name | string | *Required*.  Full name of this component which is also used as this component's catalog id.  The name includes a namespace that is dot-separated.
  25 description | string | Human-readable text blurb describing the component and the components functional purpose.
  26 component_type | string | *Required*.  Identify what containerization technology this component uses: `docker` or `cdap`.
  27
  28 ## Interfaces
  29 Interfaces are the JSON objects found under the `streams` key and the `services` key.  These are used to describe the interfaces that the component uses and the interfaces that the component provides.  The description of each interface includes the associated [data format](/components/data-formats.md).
  30
  31 ### Streams
  32  * The `streams` JSON is for specifying that you produce data that can be consumed by other components, and the streams you expect to subscribe to produced by other components. These are "fire and     forget" type interfaces where the publisher of a stream does not expect or parse a response from the subscriber.
  33 * The term `stream` here is abstract and neither refers to "CDAP streams" or "DMaaP feeds": while a stream is very likely a DMaaP feed, it could be a direct stream of data being routed via HTTP too. It     abstractly refers to a sequence of data leaving a publisher.
  34 * Streams have anonymous publish/subscribe semantics, which decouples the production of information from its consumption.
  35 * In general, components are not aware of who they are communicating with.
  36 * Instead, components that are interested in data subscribe to the relevant stream; components that generate data publish to the relevant stream.
  37 * There can be multiple publishers and subscribers to a stream. Streams are intended for unidirectional, streaming communication.
  38
  39 Streams interfaces that implement an HTTP endpoint must support POST.
  40
  41 Streams are split into:
  42
  43 Property Name | Type | Description
  44 ------------- | ---- | -----------
  45 subscribes | JSON list | *Required*.  List of all available stream interfaces that this component has that can be used for subscribing
  46 publishes | JSON list | *Required*.  List of all stream interfaces that this component will publish onto
  47
  48 #### Subscribes
  49
  50 From the example specification:
  51
  52 ```json
  53 "streams": {
  54     "subscribes": [{
  55         "format": "dcae.vnf.kpi",
  56         "version": "1.0.0",
  57         "route": "/data",        // for CDAP this value is not used
  58         "type": "http"
  59     }],
  60 ...
  61 }
  62 ```
  63
  64 This describes that `asimov.component.kpi_anomaly` exposes an HTTP endpoint called `/data` which accepts requests that have the data format of `dcae.vnf.kpi` version `1.0.0`.
  65
  66 The JSON object schema used in `subscribes`:
  67
  68 Property Name | Type | Description
  69 ------------- | ---- | -----------
  70 format | string | *Required*.  Data format id of the data format that is used by this interface
  71 version | string | *Required*.  Data format version of the data format that is used by this interface
  72 route | string | *Required*.  The HTTP route that this interface listens on
  73 type | string | *Required*. Type of stream: `http`, `message_router`, `data_router`
  74
  75 ##### Message router
  76
  77 Message router subscribers are http clients rather than http services and performs a http `GET` call.  Thus, message router subscribers description is structured like message router publishers and requires `config_key`:
  78
  79 ```json
  80 "streams": {
  81     "subscribes": [{
  82         "format": "dcae.some-format",
  83         "version": "1.0.0",
  84         "config_key": "some_format_handle",
  85         "type": "message router"
  86     }],
  87 ...
  88 }
  89 ```
  90
  91 ##### Data router
  92
  93 Data router subscribers are http or https services that handle `PUT` requests from data router.  Developers must provide the `route` or url path/endpoint that is expected to handle data router requests.  This will be used to construct the delivery url needed to register your subscriber to the provisioned feed.  Developers must also provide a `config_key` because there is dynamic configuration information associated with the feed that your application will need e.g. username and password.  See the page on [DMaaP connection objects](../dcae-cli/dmaap-connection-objects) for more details on the configuration information.
  94
  95 Example (not tied to the larger example):
  96
  97 ```json
  98 "streams": {
  99     "subscribes": [{
 100         "config_key": "some-sub-dr",
 101         "format": "sandbox.platform.any",
 102         "route": "/identity",
 103         "type": "data_router",
 104         "version": "0.1.0"
 105     }],
 106 ...
 107 }
 108 ```
 109
 110 #### Publishes
 111
 112 From the example specification:
 113
 114 ```json
 115 "streams": {
 116 ...
 117     "publishes": [{
 118         "format": "asimov.format.integerClassification",
 119         "version": "1.0.0",
 120         "config_key": "prediction",
 121         "type": "http"
 122     }]
 123 },
 124
 125 ```
 126
 127 This describes that `asimov.component.kpi_anomaly` publishes by making POST requests to streams that support the data format `asimov.format.integerClassification` version `1.0.0`.
 128
 129 The JSON object schema used in `publishes`:
 130
 131 Property Name | Type | Description
 132 ------------- | ---- | -----------
 133 format | string | *Required*.  Data format id of the data format that is used by this interface
 134 version | string | *Required*.  Data format version of the data format that is used by this interface
 135 config_key | string | *Required*.  The JSON key in the generated application configuration that will be used to pass the downstream component connection information.
 136 type | string | *Required*. Type of stream: `http`, `message router`
 137
 138 ##### Data router
 139
 140 Data router publishers are http clients that make `PUT` requests to data router.  Developers must also provide a `config_key` because there is dynamic configuration information associated with the feed that your application will need to receive e.g. publish url, username, password.  See the page on [DMaaP connection objects](../dcae-cli/dmaap-connection-objects) for more details on the configuration information.
 141
 142 Example (not tied to the larger example):
 143
 144 ```json
 145 "streams": {
 146 ...
 147     "publishes": [{
 148         "config_key": "some-pub-dr",
 149         "format": "sandbox.platform.any",
 150         "type": "data_router",
 151         "version": "0.1.0"
 152     }]
 153 }
 154 ```
 155
 156 ### Services
 157
 158 * The publish / subscribe model is a very flexible communication paradigm, but its many-to-many one-way transport is not appropriate for RPC
 159 request / reply interactions, which are often required in a distributed system.
 160 * Request / reply is done via a Service, which is defined by a pair of messages: one for the request and one for the reply.
 161
 162 Services are split into:
 163
 164 Property Name | Type | Description
 165 ------------- | ---- | -----------
 166 calls | JSON list | *Required*.  List of all service interfaces that this component will call
 167 provides | JSON list | *Required*.  List of all service interfaces that this component exposes and provides
 168
 169 #### Calls
 170 The JSON `services/calls` is for specifying that your component relies on an HTTP(S) service---your component sends that service an HTTP request, and that service responds with an HTTP reply.
 171 An example of this is how string matching (SM) depends on the AAI Broker. SM performs a synchronous REST call to the AAI broker, providing it the VMNAME of the VNF, and the AAI Broker responds with additional details about the VNF. This dependency is expressed via `services/calls`. In contrast, the output of string matching (the alerts it computes) is sent directly to policy as a fire-and-forget interface, so that is an example of a `stream`.
 172
 173 From the example specification:
 174
 175 ```json
 176 "services": {
 177     "calls": [{
 178         "config_key": "vnf-db",
 179         "request": {
 180             "format": "dcae.vnf.meta",
 181             "version": "1.0.0"
 182             },
 183         "response": {
 184             "format": "dcae.vnf.kpi",
 185             "version": "1.0.0"
 186             }
 187     }],
 188 ...
 189 }
 190 ```
 191
 192 This describes that `asimov.component.kpi_anomaly` will make HTTP calls to a downstream component that accepts requests of data format `dcae.vnf.meta` version `1.0.0` and is expecting the response to be `dcae.vnf.kpi` version `1.0.0`.
 193
 194 The JSON object schema used in `calls`:
 195
 196 Property Name | Type | Description
 197 ------------- | ---- | -----------
 198 request | JSON object | *Required*.  Description of the expected request for this downstream interface
 199 response | JSON object | *Required*.  Description of the expected response for this downstream interface
 200 config_key | string | *Required*.  The JSON key in the generated application configuration that will be used to pass the downstream component connection information.
 201
 202 The JSON object schema for both `request` and `response`:
 203
 204 Property Name | Type | Description
 205 ------------- | ---- | -----------
 206 format | string | *Required*.  Data format id of the data format that is used by this interface
 207 version | string | *Required*.  Data format version of the data format that is used by this interface
 208
 209 #### Provides
 210
 211 From the example specification:
 212
 213 ```json
 214 "services": {
 215 ...
 216     "provides": [{
 217         "route": "/score-vnf",
 218         "request": {
 219             "format": "dcae.vnf.meta",
 220             "version": "1.0.0"
 221             },
 222         "response": {
 223             "format": "asimov.format.integerClassification",
 224             "version": "1.0.0"
 225             }
 226     }]
 227 },
 228 ```
 229
 230 This describes that `asimov.component.kpi_anomaly` provides a service interface and it is exposed on the `/score-vnf` HTTP endpoint.  The endpoint accepts requests that have the data format `dcae.vnf.meta` version `1.0.0` and gives back a response of `asimov.format.integerClassification` version `1.0.0`.
 231
 232 The JSON object schema used in `provides`:
 233
 234 Property Name | Type | Description
 235 ------------- | ---- | -----------
 236 request | JSON object | *Required*.  Description of the expected request for this interface
 237 response | JSON object | *Required*.  Description of the expected response for this interface
 238 route | string | *Required*.  The HTTP route that this interface listens on
 239
 240 The JSON object schema for both `request` and `response`:
 241
 242 Property Name | Type | Description
 243 ------------- | ---- | -----------
 244 format | string | *Required*.  Data format id of the data format that is used by this interface
 245 version | string | *Required*.  Data format version of the data format that is used by this interface
 246
 247 Note, for CDAP, there is a slight variation due to the way CDAP exposes services:
 248 ```
 249       "provides":[                             // note this is a list of JSON
 250          {
 251             "request":{  ...},
 252             "response":{  ...},
 253             "service_name":"name CDAP service",
 254             "service_endpoint":"greet",         // E.g the URL is /services/service_name/methods/service_endpoint
 255             "verb":"GET"                        // GET, PUT, or POST
 256          }
 257       ]
 258 ```