[DCAEGEN2-42] Initial commit of broker

Change-Id: I1c553c82d5b39a4c134c44e2320ac0e44785e0ef
Signed-off-by: Tommy Carpenter <tommy@research.att.com>

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"
+                }
+            }
+        }
+    }
+}