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
8 # http://www.apache.org/licenses/LICENSE-2.0
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=========================================================
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.
23 # This is your document metadata
26 title: CDAP Broker API
31 description: shows some information about this service
34 description: successful response
36 $ref: '#/definitions/info'
40 description: get all applications registered with this broker
43 description: successful response
47 $ref: '#/definitions/appname'
51 description: endpoint to delete multiple applications at once. Returns an array of status codes, where statuscode[i] = response returned from DELETE(application/i)
55 description: required post body
58 $ref: '#/definitions/multideleteput'
61 description: successful response
65 $ref: '#/definitions/returncode'
67 /application/{appname}:
71 description: Name of the application.
77 description: Returns the representation of the application resource, including the links for healthcheck and metrics.
80 description: Successful response
82 $ref: '#/definitions/Application'
84 description: no app with name 'appname' registered with this broker.
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.
95 description: required put body
98 $ref: '#/definitions/appput'
102 description: Successful response
104 $ref: '#/definitions/Application'
106 description: put was performed but the appname was already registered with the broker, or Invalid PUT body
110 description: Remove an app for service and configuration discovery. This will remove the metrics and health endpoints for this app.
113 description: Successful response
115 description: no app with name 'appname' registered with this broker.
117 /application*/{appname}:
121 description: Name of the application.
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.)
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.
138 description: required put body
141 $ref: '#/definitions/hydratorappput'
145 description: Successful response
147 $ref: '#/definitions/Application'
149 description: put was performed but the appname was already registered with the broker, or Invalid PUT body
152 /application/{appname}/metrics:
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
157 # An example parameter that is in query and is required
160 description: Name of the application to get metrics for.
165 # Expected responses for this operation:
168 description: Successful response
170 $ref: '#/definitions/MetricsObject'
172 description: no app with name 'appname' registered with this broker.
174 /application/{appname}/healthcheck:
176 # This is array of GET operation parameters:
177 description: Perform a healthcheck on the running app appname.
179 # An example parameter that is in query and is required
182 description: Name of the application to get the healthcheck for.
187 # Expected responses for this operation:
191 description: Successful response, healthcheck pass
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).
195 /application/{appname}/reconfigure:
199 description: Name of the application.
204 description: Reconfigures the application.
208 description: required put body
211 $ref: '#/definitions/reconfigput'
214 description: Successful response
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
221 description: key,value object where the key is 'appmetrics' and the value is an app dependent json and specified by the component developer
230 description: application name
233 description: fully qualified url to perform healthcheck
236 description: fully qualified url to get metrics from
239 description: fully qualified url of the resource
242 description: input URL that you can POST data into (URL of the CDAP stream)
245 description: a list of HTTP services exposed by this CDAP application
248 $ref: '#/definitions/service_method'
253 reconfiguration_type:
254 description: the type of reconfiguration
256 enum: ["program-flowlet-app-config", "program-flowlet-app-preferences", "program-flowlet-smart"]
258 description: the config JSON
260 required: ["reconfiguration_type", "config"]
268 $ref: '#/definitions/appname'
271 description: an application name
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"
280 enum: ["hydrator-pipeline"]
282 description: the cdap namespace this is deployed into
284 pipeline_config_json_url:
285 description: the URL of the config.json for this pipeline
288 description: name of the CDAP stream to ingest data into this app. Should come from the developer and Tosca model.
291 description: represents a list of dependencies to be loaded for this pipeline. Not required.
294 $ref: '#/definitions/hydratordep'
295 required: ["cdap_application_type", "namespace", "pipeline_config_json_url", "streamname"]
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"
303 enum: ["program-flowlet"]
305 description: name of the CDAP stream to ingest data into this app. Should come from the developer and Tosca model.
308 description: the cdap namespace this is deployed into
311 description: the URL that the JAR you're deploying resides
314 description: the name of the CDAP artifact to be added
317 description: the version of the artifact. Must be in X.Y.Z form
319 description: the application config JSON
322 description: the application preferences JSON
327 $ref: '#/definitions/programs'
331 $ref: '#/definitions/programpref'
335 $ref: '#/definitions/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)
343 description: the name of the service
346 description: the name of the endpoint on the service
349 description: GET, POST, PUT, etc
352 description: a URL and HTTP method exposed via a CDAP service
357 description: the fully qualified URL in CDAP for this service
360 description: HTTP method you can perform on the URL, e.g., GET, PUT, etc
363 description: the list of programs in this CDAP app
367 description: must be one of flows, mapreduce, schedules, spark, workflows, workers, or services
370 description: the name of the program
374 description: an httpreturncode
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)"
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)"
384 description: the name of the artifact
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"
390 description: the URL of the artifact JAR
393 description: the URL of the properties.json if the custom artifact has UI properties. This is optional.
395 required: ["artifact_extends_header", "artifact_name", "artifact_version_header", "artifact_url"]
398 description: the list of programs in this CDAP app
402 description: must be one of flows, mapreduce, schedules, spark, workflows, workers, or services
405 description: the name of the program
408 description: the preference JSON to set for this program
412 description: some broker information
416 description: the url of the CDAP cluster API this broker is managing
418 number of applications registered:
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:
427 description: the version of the CDAP cluster this broker is managing. Note, will return UKNOWN_CDAP_VERSION if it cannot be determined.
430 description: the API version of this running broker