SQL API - Descriptions

General Details

• API Name: This is the designation that your API uses in the Illuminate system and determines the default published URL name. We recommend you use a name that is descriptive of the API so that it is easily identified when reviewing the API Logs or searching for a particular API. e.g. ContactInfo

• API Version: This is  used to help track the most current version of your APIs by incrementing it whenever you make a change to the API. When you invoke an API, if no version number is used, the API with the highest available version number is executed. It is possible to use a different API version by specifying the version number and explicitly using that in the called URL.

• API Description: While not used internally, the description entered will be displayed in the API Library. It is recommended to put a description that is both succinct and useful so that you can quickly and easily identify the full purpose of the API without having to enter the API editor to inspect it. (is this used in search?)

• API Group Name/API Tags: These two categories are for self-defined organization-specific labels that Illuminate can use to organize, sort and search your APIs. Although optional, assigning pertinent groups and tags to APIs can greatly aid in searching through the API library, especially as your library grows. 

• API Call Type: API calls can be synchronous or asynchronous. If an API call is synchronous, thet code execution will wait for the API call to return before continuing. This means that until a response is returned by the API, your application will not execute any further (until completion or timeout), which could be perceived by the user as latency or performance lag in your application. Making an API call synchronously can be beneficial, however, if there is code in your application that will only execute properly once the API response is received. Conversely, asynchronous calls do not wait and execution continues on in your program. When the call returns from the server, a "callback" function is executed.

• API Method: API Method will default to GET for a SQL API type and cannot be changed. 

• Published API URL: This is the URL Illuminate will use to run the API. This URL is view only and cannot be altered. 

API Definition

• Source: Source is the database connection the API will use to  execute the query. The source is a defined Connection. 

• SQL Query: A query is an inquiry into the database using the SELECT statement. A query is used to extract data from the database in a readable format according to the user's request. For instance, if you have an employee table, you might issue a SQL statement that returns the employee who is paid the most. This field is where you input  the query that the API will use every time it runs.

• Generate Model: Generate model will automatically determine the input and output fields used within the APIs input and response.This option will also automatically format your SQL query for easy review. Once the model is generated, the defaulted field names and settings can be modified. The field names, data type, default values and requirement parameters can be changed. 

Data Rules and Translation

• Template Name: The template name is used to distinguish specific data translation rules so that they can be reused between APIs.

• Mask All Field: This option will enable or disable all field masking for the API.

• Field Name/Actual Field Name: This set of options lets you set whether or not the API changes the name of the data field as it passes it on. This can be useful when transmitting data between different sources that don’t use the same field names in their interface definitions.

• Mask Field: Selecting the Mask Field option allows you to selectively hide or mask portions of the data field as the API passes it on. 

• Include in Response: This option allows you to select if a specific data field is included in the data returned by this API. This can be useful when using templates to quickly deselect data fields without having to create a new set of data rules.

Output Format

• Select Output Format: This option allows you to choose a format such as XML, JSON, TEXT, XModule or CSV to return your data. Example output will be shown below the selection so that you can validate formatting.