CDAP Broker API

Version: 4.0.7

- - -

- Schemes: - -

- -

Summary

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Path	Operation	Description
- / -	- GET -	- -
- /application -	- GET -	- -
- /application*/{appname} -	- PUT -	- -
- /application/delete -	- POST -	- -
- /application/{appname} -	- DELETE -	- -
	- GET -	- -
	- PUT -	- -
- /application/{appname}/healthcheck -	- GET -	- -
- /application/{appname}/metrics -	- GET -	- -
- /application/{appname}/reconfigure -	- PUT -	- -

- - - -

Paths

- - - -

GET /

shows some information about this service

- -

- - -

- -

- 200 OK - -: -
-
-
successful response
- -
-
-
- -
-
-
- info -
-
- -

- -

GET /application

get all applications registered with this broker

- -

- - -

- -

- 200 OK - -: -
-
-
successful response
- -
-
-
- -
-
-
- -
- appname - - - -
- -
-

-
- -

- -

PUT **/application*/{appname}**

(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.

- -

application/json -

required put body

- hydratorappput -

- - - - - - - - - - - - - - - - - - -


- appname -	Name of the application. -	path	string (text) - - -	- -

- -

application/json -

- -

- 200 OK - -: -
-
-
Successful response
- -
-
-
- -
-
-
- Application -
-
- -
- 400 Bad Request - -: -
-
-
put was performed but the appname was already registered with the broker, or Invalid PUT body
- -
-
-
- -
-
- -

- -

POST /application/delete

endpoint to delete multiple applications at once. Returns an array of status codes, where statuscode[i] = response returned from DELETE(application/i)

- -

required post body

- multideleteput -

- -

- 200 OK - -: -
-
-
successful response
- -
-
-
- -
-
-
- -
- returncode - - - -
- -
-

-
- -

- -

DELETE /application/{appname}

Remove an app for service and configuration discovery. This will remove the metrics and health endpoints for this app.

- -

- - - - - - - - - - - - - - - - - - -


- appname -	Name of the application. -	path	string (text) - - -	- -

- -

- 200 OK - -: -
-
-
Successful response
- -
-
-
- -
-
- -
- 404 Not Found - -: -
-
-
no app with name 'appname' registered with this broker.
- -
-
-
- -
-
- -

GET /application/{appname}

Returns the representation of the application resource, including the links for healthcheck and metrics.

- -

- - - - - - - - - - - - - - - - - - -


- appname -	Name of the application. -	path	string (text) - - -	- -

- -

- 200 OK - -: -
-
-
Successful response
- -
-
-
- -
-
-
- Application -
-
- -
- 404 Not Found - -: -
-
-
no app with name 'appname' registered with this broker.
- -
-
-
- -
-
- -

PUT /application/{appname}

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.

- -

application/json -

required put body

- appput -

- - - - - - - - - - - - - - - - - - -


- appname -	Name of the application. -	path	string (text) - - -	- -

- -

application/json -

- -

- 200 OK - -: -
-
-
Successful response
- -
-
-
- -
-
-
- Application -
-
- -
- 400 Bad Request - -: -
-
-
put was performed but the appname was already registered with the broker, or Invalid PUT body
- -
-
-
- -
-
- -

- -

GET /application/{appname}/healthcheck

Perform a healthcheck on the running app appname.

- -

- - - - - - - - - - - - - - - - - - -


- appname -	Name of the application to get the healthcheck for. -	path	string (test) - - -	- -

- -

- 200 OK - -: -
-
-
Successful response, healthcheck pass
- -
-
-
- -
-
- -
- 404 Not Found - -: -
-
-
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).
- -
-
-
- -
-
- -

- -

GET /application/{appname}/metrics

Get live (real-time) app specific metrics for the running app appname. Metrics are customized per each app by the component developer

- -

- - - - - - - - - - - - - - - - - - -


- appname -	Name of the application to get metrics for. -	path	string (test) - - -	- -

- -

- 200 OK - -: -
-
-
Successful response
- -
-
-
- -
-
-
- MetricsObject -
-
- -
- 404 Not Found - -: -
-
-
no app with name 'appname' registered with this broker.
- -
-
-
- -
-
- -

- -

PUT /application/{appname}/reconfigure

Reconfigures the application.

- -

required put body

- reconfigput -

- - - - - - - - - - - - - - - - - - -


- appname -	Name of the application. -	path	string (text) - - -	- -

- -

- 200 OK - -: -
-
-
Successful response
- -
-
-
- -
-
- -
- 400 Bad Request - -: -
-
-
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
- -
-
-
- -
-
- -

- - - -

Schema definitions

- - -

Application: - object - - - -

- -

- appname: - string - - -: -
application name
- -
- -
-
- healthcheckurl: - string - - -: -
fully qualified url to perform healthcheck
- -
- -
-
- metricsurl: - string - - -: -
fully qualified url to get metrics from
- -
- -
-
- url: - string - - -: -
fully qualified url of the resource
- -
- -
-
- connectionurl: - string - - -: -
input URL that you can POST data into (URL of the CDAP stream)
- -
- -
-
- serviceendpoints: - object[] - - -: -
a list of HTTP services exposed by this CDAP application
- -
- -
- service_method - - - -
- -
-

-

appname: - string - - - -

an application name

- -

appput: - object - - - -

- -

- cdap_application_type: - string , x ∈ { - program-flowlet - - } - - - -: -
denotes whether this is a program-flowlet style application or a hydrator pipeline. For program-flowlet style apps, this value must be "program-flowlet"
- -
- -
-
- streamname: - string - - -: -
name of the CDAP stream to ingest data into this app. Should come from the developer and Tosca model.
- -
- -
-
- namespace: - string - - -: -
the cdap namespace this is deployed into
- -
- -
-
- jar_url: - string - - -: -
the URL that the JAR you're deploying resides
- -
- -
-
- artifact_name: - string - - -: -
the name of the CDAP artifact to be added
- -
- -
-
- artifact_ver: - object - - -: -
the version of the artifact. Must be in X.Y.Z form
- -
- -
-
- app_config: - object - - -: -
the application config JSON
- -
- -
-
- app_preferences: - object - - -: -
the application preferences JSON
- -
- -
-
- programs: - object[] - - -: - -
- -
- programs - - - -
- -
-

-
- program_preferences: - object[] - - -: - -
- -
- programpref - - - -
- -
-

-
- services: - object[] - - -: - -
- -
- service_endpoint - - - -
- -
-

-

hydratorappput: - object - - - -

- -

- cdap_application_type: - string , x ∈ { - hydrator-pipeline - - } - - - - -: -
denotes whether this is a program-flowlet style application or a hydrator pipeline. For hydrator, this value must be "hydrator-pipeline"
- -
- -
-
- namespace: - string - - - -: -
the cdap namespace this is deployed into
- -
- -
-
- pipeline_config_json_url: - string - - - -: -
the URL of the config.json for this pipeline
- -
- -
-
- streamname: - string - - - -: -
name of the CDAP stream to ingest data into this app. Should come from the developer and Tosca model.
- -
- -
-
- dependencies: - object[] - - -: -
represents a list of dependencies to be loaded for this pipeline. Not required.
- -
- -
- hydratordep - - - -
- -
-

-

hydratordep: - object - - - -

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)"

- -

- artifact_extends_header: - string - - - -: -
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)"
- -
- -
-
- artifact_name: - string - - - -: -
the name of the artifact
- -
- -
-
- artifact_version_header: - string - - - -: -
the value of the header that gets passed in for artifact-version, e.g., "Artifact-Version:1.0.0-SNAPSHOT"
- -
- -
-
- artifact_url: - string - - - -: -
the URL of the artifact JAR
- -
- -
-
- ui_properties_url: - string - - -: -
the URL of the properties.json if the custom artifact has UI properties. This is optional.
- -
- -
-

info: - object - - - -

some broker information

- -

- managed cdap url: - string - - -: -
the url of the CDAP cluster API this broker is managing
- -
- -
-
- number of applications registered: - integer - - -: - -
- -
-
- uptime (s): - integer - - -: - -
- -
-
- cdap GUI port: - integer - - -: -
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: - string - - -: -
the version of the CDAP cluster this broker is managing. Note, will return UKNOWN_CDAP_VERSION if it cannot be determined.
- -
- -
-
- broker API version: - string - - -: -
the API version of this running broker
- -
- -
-

MetricsObject: - object - - - -

key,value object where the key is 'appmetrics' and the value is an app dependent json and specified by the component developer

- -

- appmetrics: - object - - -: - -
- -
-

multideleteput: - object - - - -

- -

- appnames: - object[] - - -: - -
- -
- appname - - - -
- -
-

-

programpref: - object - - - -

the list of programs in this CDAP app

- -

- program_type: - string - - -: -
must be one of flows, mapreduce, schedules, spark, workflows, workers, or services
- -
- -
-
- program_id: - string - - -: -
the name of the program
- -
- -
-
- program_pref: - object - - -: -
the preference JSON to set for this program
- -
- -
-

programs: - object - - - -

the list of programs in this CDAP app

- -

- program_type: - string - - -: -
must be one of flows, mapreduce, schedules, spark, workflows, workers, or services
- -
- -
-
- program_id: - string - - -: -
the name of the program
- -
- -
-

reconfigput: - object - - - -

- -

- reconfiguration_type: - string , x ∈ { - program-flowlet-app-config - , - program-flowlet-app-preferences - , - program-flowlet-smart - - } - - - - -: -
the type of reconfiguration
- -
- -
-
- config: - object - - - -: -
the config JSON
- -
- -
-

returncode: - integer - - - -

an httpreturncode

- -

service_endpoint: - object - - - -

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)

- -

- service_name: - string - - -: -
the name of the service
- -
- -
-
- service_endpoint: - string - - -: -
the name of the endpoint on the service
- -
- -
-
- endpoint_method: - string - - -: -
GET, POST, PUT, etc
- -
- -
-

service_method: - object - - - -

a URL and HTTP method exposed via a CDAP service

- -

- url: - string - - -: -
the fully qualified URL in CDAP for this service
- -
- -
-
- method: - string - - -: -
HTTP method you can perform on the URL, e.g., GET, PUT, etc
- -
- -
-

CDAP Broker API

Summary

Paths

GET /

GET /application

PUT /application*/{appname}

POST /application/delete

DELETE /application/{appname}

GET /application/{appname}

PUT /application/{appname}

GET /application/{appname}/healthcheck

GET /application/{appname}/metrics

PUT /application/{appname}/reconfigure

Schema definitions

Application: - object - - - -

appname: - string - - - -

appput: - object - - - -

hydratorappput: - object - - - -

hydratordep: - object - - - -

info: - object - - - -

MetricsObject: - object - - - -

multideleteput: - object - - - -

programpref: - object - - - -

programs: - object - - - -

reconfigput: - object - - - -

returncode: - integer - - - -

service_endpoint: - object - - - -

service_method: - object - - - -

PUT **/application*/{appname}**