| # ================================================================================ |
| # Copyright (c) 2017-2018 AT&T Intellectual Property. All rights reserved. |
| # ================================================================================ |
| # Licensed under the Apache License, Version 2.0 (the "License"); |
| # you may not use this file except in compliance with the License. |
| # You may obtain a copy of the License at |
| # |
| # http://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, software |
| # distributed under the License is distributed on an "AS IS" BASIS, |
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| # See the License for the specific language governing permissions and |
| # limitations under the License. |
| # ============LICENSE_END========================================================= |
| # |
| # ECOMP is a trademark and service mark of AT&T Intellectual Property. |
| # Example YAML to get you started quickly. |
| # Be aware that YAML has indentation based scoping. |
| # Code completion support is available so start typing for available options. |
| swagger: '2.0' |
| |
| # This is your document metadata |
| info: |
| version: "4.0.10" |
| title: CDAP Broker API |
| |
| paths: |
| /: |
| get: |
| description: shows some information about this service |
| responses: |
| 200: |
| description: successful response |
| schema: |
| $ref: '#/definitions/info' |
| |
| /application: |
| get: |
| description: get all applications registered with this broker |
| responses: |
| 200: |
| description: successful response |
| schema: |
| type: array |
| items: |
| $ref: '#/definitions/appname' |
| |
| /application/delete: |
| post: |
| description: endpoint to delete multiple applications at once. Returns an array of status codes, where statuscode[i] = response returned from DELETE(application/i) |
| parameters: |
| - name: postbody |
| in: body |
| description: required post body |
| required: true |
| schema: |
| $ref: '#/definitions/multideleteput' |
| responses: |
| 200: |
| description: successful response |
| schema: |
| type: array |
| items: |
| $ref: '#/definitions/returncode' |
| |
| /application/{appname}: |
| parameters: |
| - name: appname |
| in: path |
| description: Name of the application. |
| required: true |
| type: string |
| format: text |
| |
| get: |
| description: Returns the representation of the application resource, including the links for healthcheck and metrics. |
| responses: |
| 200: |
| description: Successful response |
| schema: |
| $ref: '#/definitions/Application' |
| 404: |
| description: no app with name 'appname' registered with this broker. |
| |
| put: |
| 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. |
| consumes: |
| - application/json |
| produces: |
| - application/json |
| parameters: |
| - name: putbody |
| in: body |
| description: required put body |
| required: true |
| schema: |
| $ref: '#/definitions/appput' |
| |
| responses: |
| 200: |
| description: Successful response |
| schema: |
| $ref: '#/definitions/Application' |
| 400: |
| description: put was performed but the appname was already registered with the broker, or Invalid PUT body |
| |
| |
| delete: |
| description: Remove an app for service and configuration discovery. This will remove the metrics and health endpoints for this app. |
| responses: |
| 200: |
| description: Successful response |
| 404: |
| description: no app with name 'appname' registered with this broker. |
| |
| /application*/{appname}: |
| parameters: |
| - name: appname |
| in: path |
| description: Name of the application. |
| required: true |
| type: string |
| format: text |
| |
| put: |
| 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.) |
| |
| |
| 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. |
| consumes: |
| - application/json |
| produces: |
| - application/json |
| parameters: |
| - name: putbody |
| in: body |
| description: required put body |
| required: true |
| schema: |
| $ref: '#/definitions/hydratorappput' |
| |
| responses: |
| 200: |
| description: Successful response |
| schema: |
| $ref: '#/definitions/Application' |
| 400: |
| description: put was performed but the appname was already registered with the broker, or Invalid PUT body |
| |
| |
| /application/{appname}/metrics: |
| get: |
| # This is array of GET operation parameters: |
| description: Get live (real-time) app specific metrics for the running app appname. Metrics are customized per each app by the component developer |
| parameters: |
| # An example parameter that is in query and is required |
| - name: appname |
| in: path |
| description: Name of the application to get metrics for. |
| required: true |
| type: string |
| format: test |
| |
| # Expected responses for this operation: |
| responses: |
| 200: |
| description: Successful response |
| schema: |
| $ref: '#/definitions/MetricsObject' |
| 404: |
| description: no app with name 'appname' registered with this broker. |
| |
| /application/{appname}/healthcheck: |
| get: |
| # This is array of GET operation parameters: |
| description: Perform a healthcheck on the running app appname. |
| parameters: |
| # An example parameter that is in query and is required |
| - name: appname |
| in: path |
| description: Name of the application to get the healthcheck for. |
| required: true |
| type: string |
| format: test |
| |
| # Expected responses for this operation: |
| responses: |
| # Response code |
| 200: |
| description: Successful response, healthcheck pass |
| 404: |
| 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). |
| |
| /application/{appname}/reconfigure: |
| parameters: |
| - name: appname |
| in: path |
| description: Name of the application. |
| required: true |
| type: string |
| format: text |
| put: |
| description: Reconfigures the application. |
| parameters: |
| - name: putbody |
| in: body |
| description: required put body |
| required: true |
| schema: |
| $ref: '#/definitions/reconfigput' |
| responses: |
| 200: |
| description: Successful response |
| 400: |
| 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 |
| |
| definitions: |
| MetricsObject: |
| type: object |
| description: key,value object where the key is 'appmetrics' and the value is an app dependent json and specified by the component developer |
| properties: |
| appmetrics: |
| type: object |
| |
| Application: |
| type: object |
| properties: |
| appname: |
| description: application name |
| type: string |
| healthcheckurl: |
| description: fully qualified url to perform healthcheck |
| type: string |
| metricsurl: |
| description: fully qualified url to get metrics from |
| type: string |
| url: |
| description: fully qualified url of the resource |
| type: string |
| connectionurl: |
| description: input URL that you can POST data into (URL of the CDAP stream) |
| type: string |
| serviceendpoints: |
| description: a list of HTTP services exposed by this CDAP application |
| type: array |
| items: |
| $ref: '#/definitions/service_method' |
| |
| reconfigput: |
| type: object |
| properties: |
| reconfiguration_type: |
| description: the type of reconfiguration |
| type: string |
| enum: ["program-flowlet-app-config", "program-flowlet-app-preferences", "program-flowlet-smart"] |
| config: |
| description: the config JSON |
| type: object |
| required: ["reconfiguration_type", "config"] |
| |
| multideleteput: |
| type: object |
| properties: |
| appnames: |
| type: array |
| items: |
| $ref: '#/definitions/appname' |
| |
| appname: |
| description: an application name |
| type: string |
| |
| hydratorappput: |
| type: object |
| properties: |
| cdap_application_type: |
| description: denotes whether this is a program-flowlet style application or a hydrator pipeline. For hydrator, this value must be "hydrator-pipeline" |
| type: string |
| enum: ["hydrator-pipeline"] |
| namespace: |
| description: the cdap namespace this is deployed into |
| type: string |
| pipeline_config_json_url: |
| description: the URL of the config.json for this pipeline |
| type: string |
| streamname: |
| description: name of the CDAP stream to ingest data into this app. Should come from the developer and Tosca model. |
| type: string |
| dependencies: |
| description: represents a list of dependencies to be loaded for this pipeline. Not required. |
| type: array |
| items: |
| $ref: '#/definitions/hydratordep' |
| required: ["cdap_application_type", "namespace", "pipeline_config_json_url", "streamname"] |
| |
| appput: |
| type: object |
| properties: |
| cdap_application_type: |
| 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" |
| type: string |
| enum: ["program-flowlet"] |
| streamname: |
| description: name of the CDAP stream to ingest data into this app. Should come from the developer and Tosca model. |
| type: string |
| namespace: |
| description: the cdap namespace this is deployed into |
| type: string |
| jar_url: |
| description: the URL that the JAR you're deploying resides |
| type: string |
| artifact_name: |
| description: the name of the CDAP artifact to be added |
| type: string |
| artifact_ver: |
| description: the version of the artifact. Must be in X.Y.Z form |
| app_config: |
| description: the application config JSON |
| type: object |
| app_preferences: |
| description: the application preferences JSON |
| type: object |
| programs: |
| type: array |
| items: |
| $ref: '#/definitions/programs' |
| program_preferences: |
| type: array |
| items: |
| $ref: '#/definitions/programpref' |
| services: |
| type: array |
| items: |
| $ref: '#/definitions/service_endpoint' |
| |
| service_endpoint: |
| 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) |
| type: object |
| properties: |
| service_name: |
| type: string |
| description: the name of the service |
| service_endpoint: |
| type: string |
| description: the name of the endpoint on the service |
| endpoint_method: |
| type: string |
| description: GET, POST, PUT, etc |
| |
| service_method: |
| description: a URL and HTTP method exposed via a CDAP service |
| type: object |
| properties: |
| url: |
| type: string |
| description: the fully qualified URL in CDAP for this service |
| method: |
| type: string |
| description: HTTP method you can perform on the URL, e.g., GET, PUT, etc |
| |
| programs: |
| description: the list of programs in this CDAP app |
| type: object |
| properties: |
| program_type: |
| description: must be one of flows, mapreduce, schedules, spark, workflows, workers, or services |
| type: string |
| program_id: |
| description: the name of the program |
| type: string |
| |
| returncode: |
| description: an httpreturncode |
| type: integer |
| |
| hydratordep: |
| 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)" |
| properties: |
| artifact_extends_header: |
| 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)" |
| type: string |
| artifact_name: |
| description: the name of the artifact |
| type: string |
| artifact_version_header : |
| description: the value of the header that gets passed in for artifact-version, e.g., "Artifact-Version:1.0.0-SNAPSHOT" |
| type: string |
| artifact_url: |
| description: the URL of the artifact JAR |
| type: string |
| ui_properties_url: |
| description: the URL of the properties.json if the custom artifact has UI properties. This is optional. |
| type: string |
| required: ["artifact_extends_header", "artifact_name", "artifact_version_header", "artifact_url"] |
| |
| programpref: |
| description: the list of programs in this CDAP app |
| type: object |
| properties: |
| program_type: |
| description: must be one of flows, mapreduce, schedules, spark, workflows, workers, or services |
| type: string |
| program_id: |
| description: the name of the program |
| type: string |
| program_pref: |
| description: the preference JSON to set for this program |
| type: object |
| |
| info: |
| description: some broker information |
| type: object |
| properties: |
| managed cdap url: |
| description: the url of the CDAP cluster API this broker is managing |
| type: string |
| number of applications registered: |
| type: integer |
| uptime (s): |
| type: integer |
| cdap GUI port: |
| type: integer |
| 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. |
| cdap cluster version: |
| type: string |
| description: the version of the CDAP cluster this broker is managing. Note, will return UKNOWN_CDAP_VERSION if it cannot be determined. |
| broker API version: |
| type: string |
| description: the API version of this running broker |
| |
| |
| |
| |
| |