Gitiles
Code Review Sign In
gerrit.nordix.org / onap / doc / 1f6cac44fa61db99bc530ca6513bfdccf3cc23e5 / . / docs / templates / sections / apiexample / dcaecdap.rst
blob: bc7f7bf359cba9f4815d8ce85d283886ce564b42 [file] [log] [blame]
===============
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 <#_ap |
| | | pname>`__ |
| | | > 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 |
| * | ** | | <#_hydratorapppu |
| | | *required | | t>`__ |
| | * | | |
+---------+-------------+--------------------------------------+------------------+
Responses
~~~~~~~~~
+---------+----------------------------------------------------+----------------+
| HTTP | Description | Schema |
| Code | | |
+=========+====================================================+================+
| **200** | Successful response | `Application < |
| | | #_application> |
| | | `__ |
+---------+----------------------------------------------------+----------------+
| **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* | | **postbod | required post body | `multideleteput |
| * | y** | | <#_multideletepu |
| | | *required | | 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 < |
| | | #_application> |
| | | `__ |
+---------+----------------------------------------------------+----------------+
| **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 |
| * | ** | | t>`__ |
| | | *required | | |
| | * | | |
+---------+-------------+--------------------------------------+------------------+
Responses
~~~~~~~~~
+---------+----------------------------------------------------+----------------+
| HTTP | Description | Schema |
| Code | | |
+=========+====================================================+================+
| **200** | Successful response | `Application < |
| | | #_application> |
| | | `__ |
+---------+----------------------------------------------------+----------------+
| **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 the | string (test) |
| * | ** | healthcheck for. | |
| | | *required | | |
| | * | | |
+---------+-------------+--------------------------------------+------------------+
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 (test) |
| * | ** | metrics for. | |
| | | *required | | |
| | * | | |
+---------+-------------+--------------------------------------+------------------+
Responses
~~~~~~~~~
+---------+----------------------------------------------------+----------------+
| HTTP | Description | Schema |
| Code | | |
+=========+====================================================+================+
| **200** | Successful response | `MetricsObject |
| | | <#_metricsobj |
| | | ect>`__ |
+---------+----------------------------------------------------+----------------+
| **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 <#_ |
| * | ** | | reconfigput>`__ |
| | | *required | | |
| | * | | |
+---------+-------------+--------------------------------------+------------------+
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 | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **connect | input URL that you can POST data into (URL | string |
| ionurl** | of the CDAP stream) | |
| | *optional | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **healthc | fully qualified url to perform healthcheck | string |
| heckurl** | | |
| | *optional | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **metrics | fully qualified url to get metrics from | string |
| url** | | |
| | *optional | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **service | a list of HTTP services exposed by this | < |
| endpoints** | CDAP application | `service\_method |
| | *optional | | <#_service_meth |
| * | | od>`__ |
| | | > 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\_co | the application config JSON | object |
| nfig** | | |
| | *optional | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **app\_pr | the application preferences JSON | object |
| eferences** | | |
| | *optional | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **artifac | the name of the CDAP artifact to be added | string |
| t\_name** | | |
| | *optional | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **cdap\_a | denotes whether this is a program-flowlet | enum |
| pplication\ | style application or a hydrator pipeline. | (program-flowlet |
| _type** | For program-flowlet style apps, this value | ) |
| | *optional | must be "program-flowlet" | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **jar\_ur | the URL that the JAR you’re deploying | string |
| l** | resides | |
| | *optional | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **namespa | the cdap namespace this is deployed into | string |
| ce** | | |
| | *optional | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **program | | < |
| \_preferenc | | `programpref <#_ |
| es** | | programpref>`__ |
| | *optional | | > array |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **program | | < |
| s** | | `programs <#_pro |
| | *optional | | grams>`__ |
| * | | > array |
+-------------+---------------------------------------------+------------------+
| | **service | | < |
| s** | | `service\_endpoi |
| | *optional | | nt <#_service_en |
| * | | dpoint>`__ |
| | | > array |
+-------------+---------------------------------------------+------------------+
| | **streamn | name of the CDAP stream to ingest data into | string |
| ame** | this app. Should come from the developer | |
| | *optional | and Tosca model. | |
| * | | |
+-------------+---------------------------------------------+------------------+
hydratorappput
--------------
+-------------+---------------------------------------------+------------------+
| Name | Description | Schema |
+=============+=============================================+==================+
| | **cdap\_a | denotes whether this is a program-flowlet | enum |
| pplication\ | style application or a hydrator pipeline. | (hydrator-pipeli |
| _type** | For hydrator, this value must be | ne) |
| | *required | "hydrator-pipeline" | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **depende | represents a list of dependencies to be | < |
| ncies** | loaded for this pipeline. Not required. | `hydratordep <#_ |
| | *optional | | hydratordep>`__ |
| * | | > array |
+-------------+---------------------------------------------+------------------+
| | **namespa | the cdap namespace this is deployed into | string |
| ce** | | |
| | *required | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **pipelin | the URL of the config.json for this | string |
| e\_config\_ | pipeline | |
| json\_url** | | |
| | *required | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **streamn | name of the CDAP stream to ingest data into | string |
| ame** | this app. Should come from the developer | |
| | *required | and Tosca model. | |
| * | | |
+-------------+---------------------------------------------+------------------+
hydratordep
-----------
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)"
+-------------+---------------------------------------------+------------------+
| Name | Description | Schema |
+=============+=============================================+==================+
| | **artifac | the value of the header that gets passed in | string |
| t\_extends\ | for artifact-extends, e.g., | |
| _header** | "Artifact-Extends:system:cdap-data-pipeline | |
| | *required | [4.0.1,5.0.0)" | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **artifac | the name of the artifact | string |
| t\_name** | | |
| | *required | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **artifac | the URL of the artifact JAR | string |
| t\_url** | | |
| | *required | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **artifac | the value of the header that gets passed in | string |
| t\_version\ | for artifact-version, e.g., | |
| _header** | "Artifact-Version:1.0.0-SNAPSHOT" | |
| | *required | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **ui\_pro | the URL of the properties.json if the | string |
| perties\_ur | custom artifact has UI properties. This is | |
| l** | optional. | |
| | *optional | | |
| * | | |
+-------------+---------------------------------------------+------------------+
info
----
some broker information
+-------------+---------------------------------------------+------------------+
| Name | Description | Schema |
+=============+=============================================+==================+
| | **broker | the API version of this running broker | string |
| API | | |
| version** | | |
| | *optional | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **cdap | The GUI port of the CDAP cluster this | integer |
| GUI | broker is managing. Mostly to help users of | |
| port** | this API check their application in cdap. | |
| | *optional | 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 | the url of the CDAP cluster API this broker | string |
| cdap | is managing | |
| url** | | |
| | *optional | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **number | | integer |
| of | | |
| applicati | | |
| ons | | |
| registere | | |
| d** | | |
| | *optional | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **uptime | | integer |
| (s)** | | |
| | *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 | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **reconfi | the type of reconfiguration | enum |
| guration\_t | | (program-flowlet |
| ype** | | -app-config, |
| | *required | | program-flowlet- |
| * | | app-preferences, |
| | | program-flowlet- |
| | | smart) |
+-------------+---------------------------------------------+------------------+
returncode
----------
an httpreturncode
*Type* : integer
service\_endpoint
-----------------
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)
+-------------+---------------------------------------------+------------------+
| Name | Description | Schema |
+=============+=============================================+==================+
| | **endpoin | GET, POST, PUT, etc | string |
| t\_method** | | |
| | *optional | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **service | the name of the endpoint on the service | string |
| \_endpoint* | | |
| * | | |
| | *optional | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **service | the name of the service | string |
| \_name** | | |
| | *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 |
| * | e.g., GET, PUT, etc | |
| | *optional | | |
| * | | |
+-------------+---------------------------------------------+------------------+
| | **url** | the fully qualified URL in CDAP for this | string |
| | *optional | service | |
| * | | |
+-------------+---------------------------------------------+------------------+