big-data-cluster-consume-apps.md

title	Consume applications
titleSuffix	SQL Server Big Data Clusters
description	Consume an application deployed on SQL Server Big Data Clusters using a RESTful web service.
author	jeroenterheerdt
ms.author	jterh
ms.reviewer	mikeray
ms.date	01/07/2020
ms.metadata	seo-lt-2019
ms.topic	conceptual
ms.prod	sql
ms.technology	big-data-cluster

Consume an app deployed on [!INCLUDEbig-data-clusters-2019] using a RESTful web service

[!INCLUDEtsql-appliesto-ssver15-xxxx-xxxx-xxx]

This article describes how to consume an app deployed on a SQL Server big data cluster using a RESTful web service.

Prerequisites

• SQL Server big data cluster
• azdata command-line utility
• An app deployed using either azdata or the App Deploy extension

Capabilities

After you have deployed an application to your [!INCLUDEbig-data-clusters-2019], you can access and consume that application using a RESTful web service. This enables integration of that app from other applications or services (for example, a mobile app or website). The following table describes the application deployment commands that you can use with azdata to get information about the RESTful web service for your app.

Command	Description
azdata app describe	Describe application.

You can get help with the --help parameter as in the following example:

azdata app describe --help

The following sections describe how to retrieve an endpoint for an application and how to work with the RESTful web service for application integration.

Retrieve the endpoint

The azdata app describe command provides detailed information about the app including the end point in your cluster. This is typically used by an app developer to build an app using the swagger client and using the webservice to interact with the app in a RESTful manner.

Describe your app by running a command similar to the following example:

azdata app describe --name add-app --version v1

{
  "input_param_defs": [
    {
      "name": "x",
      "type": "int"
    },
    {
      "name": "y",
      "type": "int"
    }
  ],
  "links": {
    "app": "https://10.1.1.3:30080/app/addpy/v1",
    "swagger": "https://10.1.1.3:30080/app/addpy/v1/swagger.json"
  },
  "name": "add-app",
  "output_param_defs": [
    {
      "name": "result",
      "type": "int"
    }
  ],
  "state": "Ready",
  "version": "v1"
}

Note the IP address (10.1.1.3 in this example) and the port number (30080) in the output.

One of the other ways to get this information is doing right-click Manage on the server in Azure Data Studio where you will find the endpoints of the services listed.

Generate a JWT access token

In order to access the RESTful web service for the app you have deployed you first have to generate a JWT Access token. The URL for the access token depends on the version of Big Data Cluster.

Version	URL
GDR1	https://[IP]:[PORT]/docs/swagger.json
CU1 and later	https://[IP]:[PORT]/api/v1/swagger.json

For version information, see Release history.

Open the appropriate URL in your browser using the IP address and port you retrieved running the describe command above. Sign in with the same credentials you used for azdata login.

Paste the contents of the swagger.json into the Swagger Editor to understand what methods are available:

Notice the app GET method as well as the token POST method. Since the authentication for apps uses JWT tokens, you will need to get a token my using your favorite tool to make a POST call to the token method. Here is an example of how to do just that in Postman:

The result of this request will give you a JWT access_token, which you will need to call the URL to run the app.

Execute the app using the RESTful web service

Note

If you want, you can open the URL for the swagger that was returned when you ran azdata app describe --name [appname] --version [version] in your browser, which should be similar to https://[IP]:[PORT]/app/[appname]/[version]/swagger.json. You will have to log in with the same credentials you used for azdata login. The contents of the swagger.json you can paste into Swagger Editor. You will see that the web service exposes the run method. Also note the Base URL displayed at the top.

You can use your favorite tool to call the run method (https://[IP]:30778/api/app/[appname]/[version]/run), passing in the parameters in the body of your POST request as json. In this example, we will use Postman. Before making the call, you will need to set the Authorization to Bearer Token and paste in the token you retrieved earlier. This will set a header on your request. See the screenshot below.

Next, in the requests body, pass in the parameters to the app you are calling and set the content-type to application/json:

When you send the request, you will get the same output as you did when you ran the app through azdata app run:

You have now successfully called the app through the web service. You can follow similar steps to integrate this web service in your application.

Next steps

You can also check out additional samples at App Deploy Samples.

For more information about [!INCLUDEbig-data-clusters-2019], see [What are [!INCLUDEbig-data-clusters-2019]?](big-data-cluster-overview.md).