===============
CDAP Broker API
===============

:Date:   2017-10-09

.. contents::
   :depth: 3
..

Overview
========

Version information
-------------------

*Version* : 4.0.10

Paths
=====

GET /
-----

Description
~~~~~~~~~~~

shows some information about this service

Responses
~~~~~~~~~

+---------+--------------------------------------------+-------------------+
| HTTP    | Description                                | Schema            |
| Code    |                                            |                   |
+=========+============================================+===================+
| **200** | successful response                        | `info <#_info>`__ |
+---------+--------------------------------------------+-------------------+

GET /application
----------------

Description
~~~~~~~~~~~

get all applications registered with this broker

Responses
~~~~~~~~~

+---------+-------------------------------------------+---------------+
| HTTP    | Description                               | Schema        |
| Code    |                                           |               |
+=========+===========================================+===============+
| **200** | successful response                       | `appname <#_a |
|         |                                           | ppname>`__    |
|         |                                           | (array)       |
+---------+-------------------------------------------+---------------+

PUT /application/{appname}
--------------------------

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.

Parameters
~~~~~~~~~~

+----------+---------------+---------------------------------+------------------+
| Type     | Name          | Description                     | Schema           |
+==========+===============+=================================+==================+
| **Path** | | **appname** | Name of the application.        | string (text)    |
|          | | *required*  |                                 |                  |
+----------+---------------+---------------------------------+------------------+
| **Body** | | **putbody** | required put body               | `hydratorappput  |
|          | | *required*  |                                 | <#_hydratorapppu |
|          |               |                                 | t>`__            |
+----------+---------------+---------------------------------+------------------+

Responses
~~~~~~~~~

+---------+----------------------------------------------------+---------------+
| HTTP    | Description                                        | Schema        |
| Code    |                                                    |               |
+=========+====================================================+===============+
| **200** | Successful response                                | `application  |
|         |                                                    | <#_applicatio |
|         |                                                    | n>`__         |
+---------+----------------------------------------------------+---------------+
| **400** | put was performed but the appname was already      | No Content    |
|         | registered with the broker, or Invalid PUT body    |               |
+---------+----------------------------------------------------+---------------+

Consumes
~~~~~~~~

-  ``application/json``

Produces
~~~~~~~~

-  ``application/json``

POST /application/delete
------------------------

Description
~~~~~~~~~~~

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

Parameters
~~~~~~~~~~

+----------+----------------+------------------------------+------------------+
| Type     | Name           | Description                  | Schema           |
+==========+================+==============================+==================+
| **Body** | | **postbody** | required post body           | `multideleteput  |
|          | | *required*   |                              | <#_multideletepu |
|          |                |                              | t>`__            |
+----------+----------------+------------------------------+------------------+

Responses
~~~~~~~~~

+---------+----------------------------------------------+-------------------+
| HTTP    | Description                                  | Schema            |
| Code    |                                              |                   |
+=========+==============================================+===================+
| **200** | successful response                          | `returncode       |
|         |                                              | <#_returncode>`__ |
|         |                                              | (array)           |
+---------+----------------------------------------------+-------------------+

GET /application/{appname}
--------------------------

Description
~~~~~~~~~~~

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

Parameters
~~~~~~~~~~

+----------+---------------+--------------------------------+------------------+
| Type     | Name          | Description                    | Schema           |
+==========+===============+================================+==================+
| **Path** | | **appname** | Name of the application.       | string (text)    |
|          | | *required*  |                                |                  |
+----------+---------------+--------------------------------+------------------+

Responses
~~~~~~~~~

+---------+----------------------------------------------------+---------------+
| HTTP    | Description                                        | Schema        |
| Code    |                                                    |               |
+=========+====================================================+===============+
| **200** | Successful response                                | `application  |
|         |                                                    | <#_applicatio |
|         |                                                    | n>`__         |
+---------+----------------------------------------------------+---------------+
| **404** | no app with name 'appname' registered with this    | No Content    |
|         | broker.                                            |               |
+---------+----------------------------------------------------+---------------+

PUT /application/{appname}
--------------------------

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.

Parameters
~~~~~~~~~~

+----------+---------------+--------------------------------+------------------+
| Type     | Name          | Description                    | Schema           |
+==========+===============+================================+==================+
| **Path** | | **appname** | Name of the application.       | string (text)    |
|          | | *required*  |                                |                  |
+----------+---------------+--------------------------------+------------------+
| **Body** | | **putbody** | required put body              | `appput <#_apppu |
|          | | *required*  |                                | t>`__            |
+----------+---------------+--------------------------------+------------------+

Responses
~~~~~~~~~

+---------+--------------------------------------------------+---------------+
| HTTP    | Description                                      | Schema        |
| Code    |                                                  |               |
+=========+==================================================+===============+
| **200** | Successful response                              | `Application  |
|         |                                                  | <#_applicatio |
|         |                                                  | n>`__         |
+---------+--------------------------------------------------+---------------+
| **400** | put was performed but the appname was already    | No Content    |
|         | registered with the broker, or Invalid PUT body  |               |
+---------+--------------------------------------------------+---------------+

Consumes
~~~~~~~~

-  ``application/json``

Produces
~~~~~~~~

-  ``application/json``

DELETE /application/{appname}
-----------------------------

Description
~~~~~~~~~~~

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

Parameters
~~~~~~~~~~

+----------+---------------+--------------------------------+------------------+
| Type     | Name          | Description                    | Schema           |
+==========+===============+================================+==================+
| **Path** | | **appname** | Name of the application.       | string (text)    |
|          | | *required*  |                                |                  |
+----------+---------------+--------------------------------+------------------+

Responses
~~~~~~~~~

+---------+----------------------------------------------------+----------------+
| HTTP    | Description                                        | Schema         |
| Code    |                                                    |                |
+=========+====================================================+================+
| **200** | Successful response                                | No Content     |
+---------+----------------------------------------------------+----------------+
| **404** | no app with name 'appname' registered with this    | No Content     |
|         | broker.                                            |                |
+---------+----------------------------------------------------+----------------+

GET /application/{appname}/healthcheck
--------------------------------------

Description
~~~~~~~~~~~

Perform a healthcheck on the running app appname.

Parameters
~~~~~~~~~~

+----------+---------------+--------------------------------+------------------+
| Type     | Name          | Description                    | Schema           |
+==========+===============+================================+==================+
| **Path** | | **appname** | Name of the application to get | string (text)    |
|          | | *required*  | the healthcheck for.           |                  |
+----------+---------------+--------------------------------+------------------+

Responses
~~~~~~~~~

+---------+----------------------------------------------------+----------------+
| HTTP    | Description                                        | Schema         |
| Code    |                                                    |                |
+=========+====================================================+================+
| **200** | Successful response, healthcheck pass              | No Content     |
+---------+----------------------------------------------------+----------------+
| **404** | no app with name 'appname' registered with this    | No Content     |
|         | 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
----------------------------------

Description
~~~~~~~~~~~

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

Parameters
~~~~~~~~~~

+----------+---------------+--------------------------------+------------------+
| Type     | Name          | Description                    | Schema           |
+==========+===============+================================+==================+
| **Path** | | **appname** | Name of the application to get | string (text)    |
|          | | *required*  | metrics for.                   |                  |
+----------+---------------+--------------------------------+------------------+

Responses
~~~~~~~~~

+---------+----------------------------------------------------+----------------+
| HTTP    | Description                                        | Schema         |
| Code    |                                                    |                |
+=========+====================================================+================+
| **200** | Successful response                                | `MetricsObject |
|         |                                                    | <#_metricsobje |
|         |                                                    | ct>`__         |
+---------+----------------------------------------------------+----------------+
| **404** | no app with name 'appname' registered with this    | No Content     |
|         | broker.                                            |                |
+---------+----------------------------------------------------+----------------+

PUT /application/{appname}/reconfigure
--------------------------------------

Description
~~~~~~~~~~~

Reconfigures the application.

Parameters
~~~~~~~~~~

+----------+---------------+----------------------------+--------------------+
| Type     | Name          | Description                | Schema             |
+==========+===============+============================+====================+
| **Path** | | **appname** | Name of the application.   | string (text)      |
|          | | *required*  |                            |                    |
+----------+---------------+----------------------------+--------------------+
| **Body** | | **putbody** | required put body          | `reconfigput       |
|          | | *required*  |                            | <#_reconfigput>`__ |
+----------+---------------+----------------------------+--------------------+

Responses
~~~~~~~~~

+---------+----------------------------------------------------+----------------+
| HTTP    | Description                                        | Schema         |
| Code    |                                                    |                |
+=========+====================================================+================+
| **200** | Successful response                                | No Content     |
+---------+----------------------------------------------------+----------------+
| **400** | Bad request. Can happen with 1) {appname} is not   | No Content     |
|         | 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
===========

Application
-----------

+---------------------+---------------------------------------------+------------------+
| Name                | Description                                 | Schema           |
+=====================+=============================================+==================+
| | **appname**       | application name                            | string           |
| | *optional*        |                                             |                  |
+---------------------+---------------------------------------------+------------------+
| | **connectionurl** | input URL that you can POST data into (URL  | string           |
| | *optional*        | of the CDAP stream)                         |                  |
+---------------------+---------------------------------------------+------------------+
| | **healthcheckurl**| fully qualified url to perform healthcheck  | string           |
| | *optional*        |                                             |                  |
+---------------------+---------------------------------------------+------------------+
| | **metricsurl**    | fully qualified url to get metrics from     | string           |
| | *optional*        |                                             |                  |
+---------------------+---------------------------------------------+------------------+
| | **service         | a list of HTTP services exposed by this     | `service\_method |
|  endpoints**        | CDAP application                            | <#_service_metho |
| | *optional*        |                                             | d>`__            |
|                     |                                             | (array)          |
+---------------------+---------------------------------------------+------------------+
| | **url**           | fully qualified url of the resource         | string           |
| | *optional*        |                                             |                  |
+---------------------+---------------------------------------------+------------------+

MetricsObject
-------------

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

+--------------------------------+-------------------------------------------+
| Name                           | Schema                                    |
+================================+===========================================+
| | **appmetrics**               | object                                    |
| | *optional*                   |                                           |
+--------------------------------+-------------------------------------------+

appname
-------

an application name

*Type* : string

appput
------

+-------------------------------+---------------------------------------------+--------------------+
| Name                          | Description                                 | Schema             |
+===============================+=============================================+====================+
| | **app\_config**             | the application config JSON                 | object             |
| | *optional*                  |                                             |                    |
+-------------------------------+---------------------------------------------+--------------------+
| | **app\_preferences**        | the application preferences JSON            | object             |
| | *optional*                  |                                             |                    |
+-------------------------------+---------------------------------------------+--------------------+
| | **artifact\_name**          | the name of the CDAP artifact to be added   | string             |
| | *optional*                  |                                             |                    |
+-------------------------------+---------------------------------------------+--------------------+
| | **cdap\_application\_type** | denotes whether this is a program-flowlet   | enum               |
| | *optional*                  | style application or a hydrator pipeline.   | (program-flowlet   |
|                               | For program-flowlet style apps, this value  | )                  |
|                               | must be "program-flowlet"                   |                    |
+-------------------------------+---------------------------------------------+--------------------+
| | **jar\_url**                | the URL that the JAR you’re deploying       | string             |
| | *optional*                  | resides                                     |                    |
+-------------------------------+---------------------------------------------+--------------------+
| | **namespace**               | the cdap namespace this is deployed into    | string             |
| | *optional*                  |                                             |                    |
+-------------------------------+---------------------------------------------+--------------------+
| | **program\_preferences**    |                                             | `programpref       |
| | *optional*                  |                                             | <#_programpref>`__ |
|                               |                                             | (array)            |
+-------------------------------+---------------------------------------------+--------------------+
| | **programs**                |                                             | `programs          |
| | *optional*                  |                                             | <#_programs>`__    |
|                               |                                             | (array)            |
+-------------------------------+---------------------------------------------+--------------------+
| | **services**                |                                             | `service\_endpoint |
| | *optional*                  |                                             | <#_service_endpoin |
|                               |                                             | t>`__  (array)     |
+-------------------------------+---------------------------------------------+--------------------+
| | **streamname**              | name of the CDAP stream to ingest data into | string             |
| | *optional*                  | this app. Should come from the developer    |                    |
|                               | and Tosca model.                            |                    |
+-------------------------------+---------------------------------------------+--------------------+

hydratorappput
--------------

+-----------------------------------+---------------------------------------------+---------------+
| Name                              | Description                                 | Schema        |
+===================================+=============================================+===============+
| | **cdap\_application\_TYPE**     | denotes whether this is a program-flowlet   | enum          |
|                                   | style application or a hydrator pipeline.   | (hydrator-pip |
| | *required*                      | For hydrator, this value must be            | eline)        |
|                                   | "hydrator-pipeline"                         |               |
+-----------------------------------+---------------------------------------------+---------------+
| | **dependencies**                | represents a list of dependencies to be     | `hydratordep  |
| | *optional*                      | loaded for this pipeline. Not required.     | <#_hydratorde |
|                                   |                                             | p>`__ (array) |
+-----------------------------------+---------------------------------------------+---------------+
| | **namespace**                   | the cdap namespace this is deployed into    | string        |
| | *required*                      |                                             |               |
+-----------------------------------+---------------------------------------------+---------------+
| | **pipeline\_config\_json\_url** | the URL of the config.json for this         | string        |
| | *required*                      | pipeline                                    |               |
+-----------------------------------+---------------------------------------------+---------------+
| | **streamname**                  | name of the CDAP stream to ingest data into | string        |
| | *required*                      | this app. Should come from the developer    |               |
|                                   | and Tosca model.                            |               |
+-----------------------------------+---------------------------------------------+---------------+

hydratordep
-----------

represents a hydrator pipeline dependency. An equivalent 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)"

+---------------------------------+---------------------------------------------+----------+
| Name                            | Description                                 | Schema   |
+=================================+=============================================+==========+
| | **artifact\_extends\_header** | the value of the header that gets passed in | string   |
| | *required*                    | for artifact-extends, e.g.,                 |          |
|                                 | "Artifact-Extends:system:cdap-data-pipeline |          |
|                                 | [4.0.1,5.0.0)"                              |          |
+---------------------------------+---------------------------------------------+----------+
| | **artifact\_name**            | the name of the artifact                    | string   |
| | *required*                    |                                             |          |
+---------------------------------+---------------------------------------------+----------+
| | **artifact\_url**             | the URL of the artifact JAR                 | string   |
| | *required*                    |                                             |          |
+---------------------------------+---------------------------------------------+----------+
| | **artifact\_version\_header** | the value of the header that gets passed in | string   |
| | *required*                    | for artifact-version, e.g.,                 |          |
|                                 | "Artifact-Version:1.0.0-SNAPSHOT"           |          |
+---------------------------------+---------------------------------------------+----------+
| | **ui\_properties\_url**       | the URL of the properties.json if the       | string   |
| | *optional*                    | custom artifact has UI properties. This is  |          |
|                                 | optional.                                   |          |
+---------------------------------+---------------------------------------------+----------+

info
----

some broker information

+------------------+---------------------------------------------+-----------+
| Name             | Description                                 | Schema    |
+==================+=============================================+===========+
| | **broker API   | the API version of this running broker      | string    |
|  version**       |                                             |           |
| | *optional*     |                                             |           |
+------------------+---------------------------------------------+-----------+
| | **cdap GUI     | The GUI port of the CDAP cluster this       | integer   |
|  port**          | broker is managing. Mostly to help users of |           |
| | *optional*     | this API check their application in cdap.   |           |
|                  | Note, will return UNKNOWN\_CDAP\_VERSION if |           |
|                  | it cannot be determined.                    |           |
+------------------+---------------------------------------------+-----------+
| | **cdap         | the version of the CDAP cluster this broker | string    |
|  cluster         | is managing. Note, will return              |           |
|  version**       | UKNOWN\_CDAP\_VERSION if it cannot be       |           |
| | *optional*     | determined.                                 |           |
+------------------+---------------------------------------------+-----------+
| | **managed cdap | the url of the CDAP cluster API this broker | string    |
|  url**           | is managing                                 |           |
| | *optional*     |                                             |           |
+------------------+---------------------------------------------+-----------+
| | **number       |                                             | integer   |
|  of applications |                                             |           |
|  registered**    |                                             |           |
| | *optional*     |                                             |           |
+------------------+---------------------------------------------+-----------+
| | **uptime (s)** |                                             | integer   |
| | *optional*     |                                             |           |
+------------------+---------------------------------------------+-----------+

multideleteput
--------------

+--------------------------------+----------------------------------+
| Name                           | Schema                           |
+================================+==================================+
| | **appnames**                 | `appname <#_appname>`__  (array) |
| | *optional*                   |                                  |
+--------------------------------+----------------------------------+

programpref
-----------

the list of programs in this CDAP app

+--------------+---------------------------------------------+----------+
| Name         | Description                                 | Schema   |
+==============+=============================================+==========+
| | **program\ | the name of the program                     | string   |
|  _id**       |                                             |          |
| | *optional* |                                             |          |
+--------------+---------------------------------------------+----------+
| | **program_ | the preference JSON to set for this program | object   |
|  \pref**     |                                             |          |
| | *optional* |                                             |          |
+--------------+---------------------------------------------+----------+
| | **program\ | must be one of flows, mapreduce, schedules, | string   |
|  _type**     | spark, workflows, workers, or services      |          |
| | *optional* |                                             |          |
+--------------+---------------------------------------------+----------+

programs
--------

the list of programs in this CDAP app

+--------------+---------------------------------------------+-----------+
| Name         | Description                                 | Schema    |
+==============+=============================================+===========+
| | **program\ | the name of the program                     | string    |
|  _id**       |                                             |           |
| | *optional* |                                             |           |
+--------------+---------------------------------------------+-----------+
| | **program\ | must be one of flows, mapreduce, schedules, | string    |
|  _type**     | spark, workflows, workers, or services      |           |
| | *optional* |                                             |           |
+--------------+---------------------------------------------+-----------+

reconfigput
-----------

+-----------------------------+-----------------------------+------------------+
| Name                        | Description                 | Schema           |
+=============================+=============================+==================+
| | **config**                | the config JSON             | object           |
| | *required*                |                             |                  |
+-----------------------------+-----------------------------+------------------+
| | **reconfiguration\_type** | the type of reconfiguration | enum             |
| | *required*                |                             | (program-flowlet |
|                             |                             | -app-config,     |
|                             |                             | program-flowlet- |
|                             |                             | app-preferences, |
|                             |                             | program-flowlet- |
|                             |                             | smart)           |
+-----------------------------+-----------------------------+------------------+

returncode
----------

an httpreturncode

*Type* : integer

service\_endpoint
-----------------

describes a service endpoint, including the service name, the method
name, and the method type (GET, PUT, etc, most of the time will be GET)

+--------------------------+-----------------------------------------+---------+
| Name                     | Description                             | Schema  |
+==========================+=========================================+=========+
| | **endpoint\_method**   | GET, POST, PUT, etc                     | string  |
| | *optional*             |                                         |         |
+--------------------------+-----------------------------------------+---------+
| | **service\ _endpoint** | the name of the endpoint on the service | string  |
| | *optional*             |                                         |         |
+--------------------------+-----------------------------------------+---------+
| | **service\_name**      | the name of the service                 | string  |
| | *optional*             |                                         |         |
+--------------------------+-----------------------------------------+---------+

service\_method
---------------

a URL and HTTP method exposed via a CDAP service

+--------------+---------------------------------------------+----------+
| Name         | Description                                 | Schema   |
+==============+=============================================+==========+
| | **method** | HTTP method you can perform on the URL,     | string   |
| | *optional* | e.g., GET, PUT, etc                         |          |
+--------------+---------------------------------------------+----------+
| | **url**    | the fully qualified URL in CDAP for this    | string   |
| | *optional* |                                             |          |
+--------------+---------------------------------------------+----------+