Consume an app deployed on SQL Server Big Data Clusters using a RESTful web service

Applies to: SQL Server 2019 (15.x)

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

Important

The Microsoft SQL Server 2019 Big Data Clusters add-on will be retired. Support for SQL Server 2019 Big Data Clusters will end on February 28, 2025. All existing users of SQL Server 2019 with Software Assurance will be fully supported on the platform and the software will continue to be maintained through SQL Server cumulative updates until that time. For more information, see the announcement blog post and Big data options on the Microsoft SQL Server platform.

Prerequisites

• SQL Server big data cluster
• Azure Data CLI (azdata)
• An app deployed using either azdata or the App Deploy extension

Note

When the application's yaml specification file specifies a schedule, the application will be triggered via a cron job. If your big data cluster is deployed on OpenShift, launching the cron job requires additional capabilities. See the details regarding security considerations on OpenShift for specific instructions.

Capabilities

After you have deployed an application to your SQL Server 2019 Big Data Clusters, 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

Big Data Clusters provides endpoints that you can access and consume that application using a RESTful web service, the main purpose is to facilities the interaction with other web or mobile applications and being more proactive for those microservices architecture. 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'll find the endpoints of the services listed.

Generate a JWT access token

To access the RESTful web service for the app you've 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

From the output of previous example, CU4 release and the IP address of controller (10.1.1.3 in the example) and the port number (30080), the URL would look like the following:

   https://10.1.1.3 :30080/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 is GET method and to get the token would use POST method. Since the authentication for apps uses JWT tokens, you'll need to get a token my using your favorite tool to make a POST call to the token method. With the same example, the URL to get JWT token would look like the follows:

   https://10.1.1.3 :30080/api/v1/token

Here is an example of how to do just that in Postman:

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

Execute the app using the RESTful web service

There are multiple ways to consume an app on SQL Server Big Data Clusters, you can choose to use azdata app run command. This section will demonstrate how to use common developer tools such as Postman to execute the app.

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.

Note

You'll have to log in with the same credentials you used for azdata login. With the same example, the command would look like the follows :

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

The contents of the swagger.json you can paste into Swagger Editor. You'll see that the web service exposes the run method, and underneath it went through application proxy, which is a web API that authenticates users and then routes the requests through to the applications. Notice that the Base URL displayed at the top. You can use tool of your choice 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'll use Postman. Before making the call, you'll 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're calling and set the content-type to application/json:

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

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

Next steps

Explore how to Monitor applications on big data clusters for more information. You can also check out additional samples at App Deploy Samples.

For more information about SQL Server Big Data Clusters, see What are SQL Server 2019 Big Data Clusters.