/features/httpaccess

HTTP Access

Introduction

Enzo Server allows requests to be made using HTTP/S requests in a way that is conceptually similar to the SQL command pattern. This section provides information on how to access Enzo adapters using HTTP requests.

You can configure Enzo to accept HTTP and/or HTTPS requests by changing the configuration file of the service. Please contact support on how to do that.

The ability to listen to HTTP/S commands allows you to build applications easily from any HTTP-enabled client, such as a mobile device, and IoT device, web platforms and event hosted environments (such as a SaaS service, Azure Functions and AWS Lambda Functions).

HTTP Command Pattern

When calling a specific adapter through Enzo, developers only need to know which URL to call and add query strings, headers and/or a body that represent the parameters for the operation being performed. The URL is constructed by appending the name of the adapter and the method to the end of the Enzo Server HTTP endpoint:

HTTPS://ENZO_URI:ENZO_PORT/bsc/ADAPTERNAME/OPERATIONNAME

For example the following are valid URI requests calling Enzo Online:

https://enzodemo:19551/bsc/db/executesql
https://enzodemo:19551/bsc/azurebus/createqueue
https://enzodemo:19551/bsc/messaging/sendsmtp

The parameters to include as part of a call are the same as those needed for SQL calls. Some of the parameters are required. The service connection information is provided by the _configName parameter; this is the name of the configuration setting you create in the Enzo Portal.

Authentication

Authenticating with Enzo using HTTP requests is done through an authentication token assigned to the login you want to use. You can access the authentication token of a user using Enzo Manager.

You can find the Auth Token of a login by select the Configuration -> Manager Logins menu in Enzo Manager. Click on the Copy AuthToken button to copy the Auth Token in memory.

You send the shared key using the authToken parameter as a Header, a Query String parameter, or a Form Parameter when using POST operations (see Passing Parameters for additional information). The authToken maps to the Enzo Login you want to use.

authToken: YOUR_AUTH_TOKEN

Configuration Settings

HTTP/S requests sent to Enzo are identified by their URI; the URI indicates which adapter is being called, and the last part of the URL indicates which method is being invoked. In order to call the service, Enzo also needs to know the adapter credentials to use: the configuration settings.

Enzo determines which configuration setting to use by inspecting three pieces of information: the adapter name (part of the URL), your Authentication Token (authToken parameter), and the configuration name (_configName parameter).

For example, the following REST command calls the DB service's ExecuteSQL command, and loads the CC1 configuration for your account. The CC1 configuration setting holds the database connection string that Enzo will use to execute the SQL statement you want to run.

    POST ENZO_URI:ENZO_PORT/bsc/db/executesql HTTP/1.1
    authToken: YOUR_AUTH_TOKEN
    _configName: CC1
    sql: SELECT * FROM sys.tables

Configuration settings are stored centrally securely; sensitive information is encrypted. See the Configuration Settings section for more information.

Passing Parameters

Most HTTP/S operations called through Enzo require passing parameters for the call to succeed. While this documentation uses Headers to outline the various parameters available, all these parameters can be specified as a combination of Query Strings, Headers and/or Body.

Required parameters must be provided with every call to Enzo

Parameters sent as a Query String or a Header should be URL Encoded

For example, the following REST command uses Headers to specify the authToken, the _configName and the SQL parameters.

    POST ENZO_URI:ENZO_PORT/bsc/db/executesql HTTP/1.1
    authToken: YOUR_AUTH_TOKEN
    _configName: CC1
    sql: SELECT+*+FROM+sys.tables

The following example uses the QueryString to pass the authToken, a Header for the configuration name, and the Body of the request to send the SQL parameter. When using the body of a request the Content-Type must be set to application/x-www-form-urlencoded.

    POST ENZO_URI:ENZO_PORT/bsc/db/executesql?authToken=YOUR_AUTH_TOKEN HTTP/1.1
    Content-Type: application/x-www-form-urlencoded
    _configName: CC1

    sql=SELECT * FROM sys.tables

Returned Data

By default all data is returned as a JSON document when calling service methods exposed by Enzo. It is also possible to request XML being returned back.

To return XML instead of JSON, simply add .xml at the end of the operation name.

For example, the following REST command returns data as an XML document. Replacing .xml by .json, or simply removing .xml would return data in JSON format.

    POST ENZO_URI:ENZO_PORT/bsc/azurestorage/getqueuedetails.xml HTTP/1.1
    authToken: YOUR_AUTH_TOKEN
    _configName: CC1
    name: integrationqueue

The layout of returned data is as follows for JSON and XML documents: