[DCAEGEN2-42] Initial commit of broker

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

1 files changed, 418 insertions, 0 deletions

diff --git a/swagger/swagger.yaml b/swagger/swagger.yaml
new file mode 100644
index 0000000..506908f
--- /dev/null
+++ b/swagger/swagger.yaml
@@ -0,0 +1,418 @@
+# 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.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.)
+        
+      
+        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
+        
+
+ 
+  
+