aboutsummaryrefslogtreecommitdiffstats
path: root/swagger/swagger.json
diff options
context:
space:
mode:
Diffstat (limited to 'swagger/swagger.json')
-rw-r--r--swagger/swagger.json560
1 files changed, 560 insertions, 0 deletions
diff --git a/swagger/swagger.json b/swagger/swagger.json
new file mode 100644
index 0000000..4490a99
--- /dev/null
+++ b/swagger/swagger.json
@@ -0,0 +1,560 @@
+{
+ "swagger": "2.0",
+ "info": {
+ "version": "4.0.3",
+ "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.)\n\nRegister 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": {
+ "description": "Get live (real-time) app specific metrics for the running app appname. Metrics are customized per each app by the component developer",
+ "parameters": [
+ {
+ "name": "appname",
+ "in": "path",
+ "description": "Name of the application to get metrics for.",
+ "required": true,
+ "type": "string",
+ "format": "test"
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful response",
+ "schema": {
+ "$ref": "#/definitions/MetricsObject"
+ }
+ },
+ "404": {
+ "description": "no app with name 'appname' registered with this broker."
+ }
+ }
+ }
+ },
+ "/application/{appname}/healthcheck": {
+ "get": {
+ "description": "Perform a healthcheck on the running app appname.",
+ "parameters": [
+ {
+ "name": "appname",
+ "in": "path",
+ "description": "Name of the application to get the healthcheck for.",
+ "required": true,
+ "type": "string",
+ "format": "test"
+ }
+ ],
+ "responses": {
+ "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"
+ }
+ }
+ }
+ }
+}