path: root/docs/sections/apis/cdapbroker.yaml

# 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