docs/sections/apis/cdapbroker.yaml

   1 # ================================================================================
   2 # Copyright (c) 2017-2018 AT&T Intellectual Property. All rights reserved.
   3 # ================================================================================
   4 # Licensed under the Apache License, Version 2.0 (the "License");
   5 # you may not use this file except in compliance with the License.
   6 # You may obtain a copy of the License at
   7 #
   8 #     http://www.apache.org/licenses/LICENSE-2.0
   9 #
  10 # Unless required by applicable law or agreed to in writing, software
  11 # distributed under the License is distributed on an "AS IS" BASIS,
  12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 # See the License for the specific language governing permissions and
  14 # limitations under the License.
  15 # ============LICENSE_END=========================================================
  16 #
  17 # ECOMP is a trademark and service mark of AT&T Intellectual Property.
  18 # Example YAML to get you started quickly.
  19 # Be aware that YAML has indentation based scoping.
  20 # Code completion support is available so start typing for available options.
  21 swagger: '2.0'
  22
  23 # This is your document metadata
  24 info:
  25   version: "4.0.10"
  26   title: CDAP Broker API
  27
  28 paths:
  29   /:
  30     get:
  31       description: shows some information about this service
  32       responses:
  33         200:
  34           description: successful response
  35           schema:
  36             $ref: '#/definitions/info'
  37
  38   /application:
  39     get:
  40       description: get all applications registered with this broker
  41       responses:
  42         200:
  43           description: successful response
  44           schema:
  45             type: array
  46             items:
  47               $ref: '#/definitions/appname'
  48
  49   /application/delete:
  50     post:
  51       description: endpoint to delete multiple applications at once. Returns an array of status codes, where statuscode[i] = response returned from DELETE(application/i)
  52       parameters:
  53         - name: postbody
  54           in: body
  55           description: required post body
  56           required: true
  57           schema:
  58             $ref: '#/definitions/multideleteput'
  59       responses:
  60         200:
  61           description: successful response
  62           schema:
  63             type: array
  64             items:
  65               $ref: '#/definitions/returncode'
  66
  67   /application/{appname}:
  68     parameters:
  69       - name: appname
  70         in: path
  71         description: Name of the application.
  72         required: true
  73         type: string
  74         format: text
  75
  76     get:
  77       description: Returns the representation of the application resource, including the links for healthcheck and metrics.
  78       responses:
  79         200:
  80           description: Successful response
  81           schema:
  82             $ref: '#/definitions/Application'
  83         404:
  84           description: no app with name 'appname' registered with this broker.
  85
  86     put:
  87       description: Register an app for service and configuration discovery. This will light up a metrics and health endpoint for this app. `appname` is assumed to also be the key in  consul.
  88       consumes:
  89         - application/json
  90       produces:
  91         - application/json
  92       parameters:
  93         - name: putbody
  94           in: body
  95           description: required put body
  96           required: true
  97           schema:
  98             $ref: '#/definitions/appput'
  99
 100       responses:
 101         200:
 102           description: Successful response
 103           schema:
 104             $ref: '#/definitions/Application'
 105         400:
 106           description: put was performed but the appname was already registered with the broker, or Invalid PUT body
 107
 108
 109     delete:
 110       description: Remove an app for service and configuration discovery. This will remove the metrics and health endpoints for this app.
 111       responses:
 112         200:
 113           description: Successful response
 114         404:
 115           description: no app with name 'appname' registered with this broker.
 116
 117   /application*/{appname}:
 118     parameters:
 119       - name: appname
 120         in: path
 121         description: Name of the application.
 122         required: true
 123         type: string
 124         format: text
 125
 126     put:
 127       description: (This is a hacky way of supporting "oneOf" because Swagger does not support oneOf https://github.com/OAI/OpenAPI-Specification/issues/333. This is the same endpoint as PUT /application/appname, except the PUT body is different.)
 128
 129
 130         Register a hydrator app for service and configuration discovery. This will light up a metrics and health endpoint for this app. `appname` is assumed to also be the key in  consul.
 131       consumes:
 132         - application/json
 133       produces:
 134         - application/json
 135       parameters:
 136         - name: putbody
 137           in: body
 138           description: required put body
 139           required: true
 140           schema:
 141             $ref: '#/definitions/hydratorappput'
 142
 143       responses:
 144         200:
 145           description: Successful response
 146           schema:
 147             $ref: '#/definitions/Application'
 148         400:
 149           description: put was performed but the appname was already registered with the broker, or Invalid PUT body
 150
 151
 152   /application/{appname}/metrics:
 153     get:
 154       # This is array of GET operation parameters:
 155       description: Get live (real-time) app specific metrics for the running app appname. Metrics are customized per each app by the component developer
 156       parameters:
 157         # An example parameter that is in query and is required
 158         - name: appname
 159           in: path
 160           description: Name of the application to get metrics for.
 161           required: true
 162           type: string
 163           format: test
 164
 165       # Expected responses for this operation:
 166       responses:
 167         200:
 168           description: Successful response
 169           schema:
 170             $ref: '#/definitions/MetricsObject'
 171         404:
 172           description: no app with name 'appname' registered with this broker.
 173
 174   /application/{appname}/healthcheck:
 175     get:
 176       # This is array of GET operation parameters:
 177       description: Perform a healthcheck on the running app appname.
 178       parameters:
 179         # An example parameter that is in query and is required
 180         - name: appname
 181           in: path
 182           description: Name of the application to get the healthcheck for.
 183           required: true
 184           type: string
 185           format: test
 186
 187       # Expected responses for this operation:
 188       responses:
 189         # Response code
 190         200:
 191           description: Successful response, healthcheck pass
 192         404:
 193           description: no app with name 'appname' registered with this broker, or the healthcheck has failed (though I would like to disambiguiate from the first case, CDAP returns a 404 for this).
 194
 195   /application/{appname}/reconfigure:
 196     parameters:
 197       - name: appname
 198         in: path
 199         description: Name of the application.
 200         required: true
 201         type: string
 202         format: text
 203     put:
 204       description: Reconfigures the application.
 205       parameters:
 206         - name: putbody
 207           in: body
 208           description: required put body
 209           required: true
 210           schema:
 211             $ref: '#/definitions/reconfigput'
 212       responses:
 213         200:
 214           description: Successful response
 215         400:
 216           description: Bad request. Can happen with 1)  {appname} is not registered with the broker, 2) the required PUT body is wrong, or 3) the smart interface was chosen and none of the config keys match anything in app_config or app_preferences
 217
 218 definitions:
 219   MetricsObject:
 220     type: object
 221     description: key,value object where the key is 'appmetrics' and the value is an app dependent json and specified by the component developer
 222     properties:
 223       appmetrics:
 224         type: object
 225
 226   Application:
 227     type: object
 228     properties:
 229       appname:
 230         description: application name
 231         type: string
 232       healthcheckurl:
 233         description: fully qualified url to perform healthcheck
 234         type: string
 235       metricsurl:
 236         description: fully qualified url to get metrics from
 237         type: string
 238       url:
 239         description: fully qualified url of the resource
 240         type: string
 241       connectionurl:
 242         description: input URL that you can POST data into (URL of the CDAP stream)
 243         type: string
 244       serviceendpoints:
 245         description: a list of HTTP services exposed by this CDAP application
 246         type: array
 247         items:
 248           $ref: '#/definitions/service_method'
 249
 250   reconfigput:
 251     type: object
 252     properties:
 253       reconfiguration_type:
 254         description: the type of reconfiguration
 255         type: string
 256         enum: ["program-flowlet-app-config", "program-flowlet-app-preferences", "program-flowlet-smart"]
 257       config:
 258         description: the config JSON
 259         type: object
 260     required: ["reconfiguration_type", "config"]
 261
 262   multideleteput:
 263     type: object
 264     properties:
 265       appnames:
 266         type: array
 267         items:
 268           $ref: '#/definitions/appname'
 269
 270   appname:
 271     description: an application name
 272     type: string
 273
 274   hydratorappput:
 275     type: object
 276     properties:
 277       cdap_application_type:
 278         description: denotes whether this is a program-flowlet style application or a hydrator pipeline. For hydrator, this value must be "hydrator-pipeline"
 279         type: string
 280         enum: ["hydrator-pipeline"]
 281       namespace:
 282         description: the cdap namespace this is deployed into
 283         type: string
 284       pipeline_config_json_url:
 285         description: the URL of the config.json for this pipeline
 286         type: string
 287       streamname:
 288         description: name of the CDAP stream to ingest data into this app. Should come from the developer and Tosca model.
 289         type: string
 290       dependencies:
 291         description: represents a list of dependencies to be loaded for this pipeline. Not required.
 292         type: array
 293         items:
 294           $ref: '#/definitions/hydratordep'
 295     required: ["cdap_application_type", "namespace", "pipeline_config_json_url", "streamname"]
 296
 297   appput:
 298     type: object
 299     properties:
 300       cdap_application_type:
 301         description: denotes whether this is a program-flowlet style application or a hydrator pipeline. For program-flowlet style apps, this value must be "program-flowlet"
 302         type: string
 303         enum: ["program-flowlet"]
 304       streamname:
 305         description: name of the CDAP stream to ingest data into this app. Should come from the developer and Tosca model.
 306         type: string
 307       namespace:
 308         description: the cdap namespace this is deployed into
 309         type: string
 310       jar_url:
 311         description: the URL that the JAR you're deploying resides
 312         type: string
 313       artifact_name:
 314         description: the name of the CDAP artifact to be added
 315         type: string
 316       artifact_ver:
 317         description: the version of the artifact. Must be in X.Y.Z form
 318       app_config:
 319         description: the application config JSON
 320         type: object
 321       app_preferences:
 322         description: the application preferences JSON
 323         type: object
 324       programs:
 325         type: array
 326         items:
 327           $ref: '#/definitions/programs'
 328       program_preferences:
 329         type: array
 330         items:
 331           $ref: '#/definitions/programpref'
 332       services:
 333         type: array
 334         items:
 335           $ref: '#/definitions/service_endpoint'
 336
 337   service_endpoint:
 338     description: descirbes a service endpoint, including the service name, the method name, and the method type (GET, PUT, etc, most of the time will be GET)
 339     type: object
 340     properties:
 341       service_name:
 342         type: string
 343         description: the name of the service
 344       service_endpoint:
 345         type: string
 346         description: the name of the endpoint on the service
 347       endpoint_method:
 348         type: string
 349         description: GET, POST, PUT, etc
 350
 351   service_method:
 352     description: a URL and HTTP method exposed via a CDAP service
 353     type: object
 354     properties:
 355       url:
 356         type: string
 357         description: the fully qualified URL in CDAP for this service
 358       method:
 359         type: string
 360         description: HTTP method you can perform on the URL, e.g., GET, PUT, etc
 361
 362   programs:
 363     description: the list of programs in this CDAP app
 364     type: object
 365     properties:
 366       program_type:
 367         description: must be one of flows, mapreduce, schedules, spark, workflows, workers, or services
 368         type: string
 369       program_id:
 370         description: the name of the program
 371         type: string
 372
 373   returncode:
 374     description: an httpreturncode
 375     type: integer
 376
 377   hydratordep:
 378     description: represents a hydrator pipeline dependency. An equivelent to the following CURLs are formed with the below four params shown in CAPS "curl -v -w"\n" -X POST http://cdapurl:11015/v3/namespaces/setelsewhere/artifacts/ARTIFACT_NAME -H "Artifact-Extends:ARTIFACT_EXTENDS_HEADER"  -H “Artifact-Version:ARTIFACT_VERSION_HEADER” --data-binary @(DOWNLOADED FROM ARTIFACT_URL)","curl -v -w"\n" -X PUT http://cdapurl:11015/v3/namespaces/setelsewhere/artifacts/ARTIFACT_NAME/versions/ARTIFACT_VERSION_HEADER/properties -d (DOWNLOADED FROM UI_PROPERTIES_URL)"
 379     properties:
 380       artifact_extends_header:
 381         description: the value of the header that gets passed in for artifact-extends, e.g., "Artifact-Extends:system:cdap-data-pipeline[4.0.1,5.0.0)"
 382         type: string
 383       artifact_name:
 384         description: the name of the artifact
 385         type: string
 386       artifact_version_header :
 387         description: the value of the header that gets passed in for artifact-version, e.g., "Artifact-Version:1.0.0-SNAPSHOT"
 388         type: string
 389       artifact_url:
 390         description: the URL of the artifact JAR
 391         type: string
 392       ui_properties_url:
 393         description: the URL of the properties.json if the custom artifact has UI properties. This is optional.
 394         type: string
 395     required: ["artifact_extends_header", "artifact_name", "artifact_version_header", "artifact_url"]
 396
 397   programpref:
 398     description: the list of programs in this CDAP app
 399     type: object
 400     properties:
 401       program_type:
 402         description: must be one of flows, mapreduce, schedules, spark, workflows, workers, or services
 403         type: string
 404       program_id:
 405         description: the name of the program
 406         type: string
 407       program_pref:
 408         description: the preference JSON to set for this program
 409         type: object
 410
 411   info:
 412     description: some broker information
 413     type: object
 414     properties:
 415       managed cdap url:
 416         description: the url of the CDAP cluster API this broker is managing
 417         type: string
 418       number of applications registered:
 419         type: integer
 420       uptime (s):
 421         type: integer
 422       cdap GUI port:
 423         type: integer
 424         description: The GUI port of the CDAP cluster this broker is managing. Mostly to help users of this API check their application in cdap. Note, will return UNKNOWN_CDAP_VERSION if it cannot be determined.
 425       cdap cluster version:
 426         type: string
 427         description: the version of the CDAP cluster this broker is managing. Note, will return UKNOWN_CDAP_VERSION if it cannot be determined.
 428       broker API version:
 429         type: string
 430         description: the API version of this running broker
 431
 432
 433
 434
 435