API Properties

Control the API details, such as enabling your API and selecting your authentication provider, and define the individual API attributes.
lac52
As an administrator, you can control the API details, such as enabling your API and selecting your authentication provider, and you can define the individual API attributes. Manage your API using the fields that are on the 
Details
 tab and the 
Settings
 tab.
These options are API-level settings. Server-level settings override API-level settings.
For more information about server-level settings, see API Server Startup Options.
In this article:
Control the API Details
  1. In the Create section, click 
    API Properties
    .
    The 
    Overview
     tab appears.
  2. Click the 
    Details
     tab.
  3. Define the following fields and options that are on the 
    Details
     tab:
    API name
     
    The name by which you refer to this API. Enter a name that is meaningful to you.
    Examples:
     Sales data or Accounts Receivable
    URL fragment
    The part of your URL for your API that is specific to your API. Define a short URL fragment. Enter only characters that are valid in a URL. API Creator replaces invalid characters with underscores. API URL names must be unique within your account.
    Enabled
    Defines whether your API can accept incoming requests.
    Default:
     Selected
    Authentication provider
    Specifies the authentication provider for your API. API users access your API using an authentication token. You can also require that API users authenticate using credentials (username and password).
    Options:
    Default:
     Built-in authentication
  4. Save your changes.
The details for your API are saved.
Define the API Settings
You can define individual API attributes using the fields that are on the Settings page.
Follow these steps:
 
  1. In the Create section, click 
    API Properties
    .
    The 
    Overview
     tab appears.
  2. Click the 
    Settings
     tab.
    For more information about fields on this tab, see the context help.
Ignore Client Attempts to Update Aggregate Values
You can authorize 
CA Live API Creator
 to ignore client attempts to update aggregate (sum, count, min, max) values and to throw exceptions by selecting the 
Aggregate Default Override
 checkbox that is on the 
Settings
 tab. By default, 
CA Live API Creator
 initializes aggregates to zero ('0') on insert, regardless of the client-supplied value.
Allow All API Calls using HTTP and HTTPS
You can allow all API calls using HTTP and HTTPS by clearing the 
HTTPS only
 checkbox that is on the 
Settings
 tab. By default, your API allows all API calls. If security is not a major concern for your API, then allow all API calls using HTTP or HTTPS.
Clearing this option does not guarantee that the caller used HTTPS. Due to issues related to firewalls and load balancers, a caller can fake this. You can force API calls to use HTTPS by turning off the HTTP endpoint on your web servers. This is a general HTTP issue.
Change the Metadata Section Name That is Included in JSON Objects
CA Live API Creator
 returns JSON objects that include the 
@metadata
 section. If this causes an issue for your environment, you can change the section name for your API. Enter a unique value in the 
Metadata name
 field that is on the 
Settings
 tab.
Best Practice: 
Choose a name that is unlikely to clash with a column name or a resource attribute name, such as 
__metadata__
 .
For more information about how to use the JSON object, see JavaScript.
Exclude the Metadata from Responses (GET only)
You can specify that API endpoints exclude the metadata from the response by clearing the 
Include metadata section in responses
 checkbox that is on the 
Settings
 tab. By default, API endpoints include the metadata section in your responses.
This option is applicable only to GET responses. POST, PUT, and DELETE responses include metadata in the 
txSummary
, and return the affected rows and a summary of the rules that 
CA Live API Creator
 executed.
For more information about response formats, including how to use the 
nometa
 URL variable, see Response Formats.
If you have specified that API endpoints exclude the metadata from responses, you can override this setting on a per-request basis by adding the 
nometa
 URL variable to the request using the following syntax:
nometa=false
Define the Number of Characters or Bytes used to Calculate the checksum Value
You can define the number of characters or bytes used to calculate the 
checksum
 value using the 
Checksum Size Limit
 field that is on the 
Settings
 tab. If the column is larger than this setting, API Server computes the 
checksum
 value using the total size and the checksum value of the first n bytes/characters, where n is the value you define in the 
Checksum Size Limit
 field. This setting is unrelated to the value format (
inline
 or 
deferred
) that API Server returns and can be larger or smaller than the default inline limit (the default value for the 
inlinelimit
 query parameter).
For more information about Binary Large OBject (BLOB) and Character Large OBject (CLOB) value formats, see BLOB, CLOB, Large Strings, Large Binary.
Inline Limit Default
You can define the default values for the 
inlinelimit
 query parameter (if not provided as a request parameter) by entering the value in the 
Inline Limit Default
 field that is on the 
Settings
 tab.
For more information about how to choose how API Creator emits binary data, including how this API setting works when the 
Force Binary Data as an Object
 checkbox is selected, see Use Binary Data and the inline help.
Control the Number of Table-Based Resource Rows Returned
You can configure pagination on large result sets that 
CA Live API Creator
 returns for your API. You can control the maximum number of rows that 
CA Live API Creator
 returns at each level of a resource endpoint per request by defining the value for the 
Page Size Default 
field that is on the 
Settings
 tab. The default value is 20.
You can override this setting on a per-GET-request basis. For more information about how to override this setting on a per-GET-request basis, see Pagination.
Control the Number of Queries to Populate Table-Based Subresource Rows
You can control the number of queries that 
CA Live API Creator
 executes to return the rows for table-based subresources by defining the value for the 
Chunk Size Default 
field that is on the 
Settings
 tab. The default value is 20. For example, you have created a 
Customers
 resource and an 
Orders
 subresource. 
CA Live API Creator
 reads 20 customers (the first page in a single query, based on the value for the 
Page Size Default 
field) and retrieves orders for these customers by chunks, based on the value for the 
Chunk Size Default
 field by issuing SQL queries. This setting can be especially helpful when you have set a large 
Page Size Default
 value. You can override this setting on a per-request basis by adding the 
chunksize
 attribute as a URL parameter.
Stored Procedure Row Limit
You can define the maximum number of rows that are returned for each result set returned by a stored procedure using the 
Stored Procedure Row Limit
 field that is on the 
Settings
 tab. Result sets are not pageable. This value is a value in the JSON telling you the limit was exceeded.
Stored Procedure Inline Limit
Values that are returned in a stored procedure determine when to inline using the value that you set for the 
Stored Procedure Row Limit
 field that is on the 
Settings
 tab. URLs cannot be generated for 
deferred
 links. When a value is exceeds the value set in this field, the length is returned.
Permit Authorization Parameter in URLs
By default, API users can specify their authentication token as a URL parameter using the following syntax:
…&auth=123456789:1
API users can retrieve the contents of BLOBs from an HTML document using an 
href
 , can invoke GET requests from a browser instead of setting HTTP headers, and can invoke POST/PUT/DELETE requests, but this is not useful typically.
To disallow API users from specifying their authentication token as a URL parameter, clear the 
Permit Authorization parameter in URL
 checkbox that is on the 
Settings
 tab.
Authorizing API users to specify their authentication token as a URL parameter has security implications. Browsers can remember URLs and URLs are typically logged in servers and routers.
Specify URLs for Documentation
You can specify URLs for documentation. Specify the URLs in the 
Tech docs URL
 and 
User docs URL
 fields that is on the 
Settings
 tab. The links must be HTTPS (for example, you can designate Google Sites).
Describe the Expected Response Format for your API
You can change the expected response format globally across your API. On the Settings tab, define the 
Default response format
 field. Select a value from the drop-down:
  • csv.
     Comma-separated values, each record is separated by a line end. Resources are flattened out to the topmost level.
  • json. 
    (Default) JSON is a ubiquitous format on the web and the default output of API Server.
  • jsonObject. 
    The object format for JSON changes the hierarchy of the data that is returned, putting the returned records in a nested "data" attribute.
  • xml.
    Restructures metadata into XML tag attributes.
The default value is 
json
.
For more information about response formats, including how to change the expected response format for a request using the 
Response Format
 drop-down and how to override the API default response format settings on a per-request basis, see the context help or Response Formats.
Enable Access to Swagger Documentation without Authentication
You can allow the discovery of the API Swagger doc without authentication by selecting the 
Allow Swagger without authentication
 checkbox that is on the 
Settings
 tab. Allowing the discovery of the API Swagger doc without authentication is useful. Many Swagger consumers do not support authentication, even though the Swagger standard does. If you must connect your API to a Swagger consumer that does not support authentication, select this checkbox temporarily, then clear it after you retrieve the API.
Default:
 Cleared
Optional:
 Yes
To retrieve the Swagger schema, use a URL similar to the following:
https://myserver.acme.com/rest/acme/proj1/v1/@docs
For more information about the Swagger "standard", see the Swagger site.
Enable Tracking and Persistence of Audit Logs
You can enable tracking and persistence of audit logs for all PUT, POST, and DELETE transactions that API Server writes to an audit database by selecting the 
Audit User Transactions
 checkbox that is on the 
Settings
 tab. For example, you can have API Server write audit transaction details to MongoDB.
For more information about how set up for auditing user transaction details, see Customize your API to Audit User Transaction Details.
Turn off Regular Filters
To turn off regular filters and sorts, select the 
Disallow free-form filters and sorts
 checkbox that is on the 
Settings
 tab. By default, this checkbox is cleared and requests can specify a filter or sort in the URL and can access your data.
For more information:
  • About filters, including the difference between regular filters and named filters and how to define system filters and user filters, see Structured Filters.
  • About sorts, including the difference between regular sorts and named sorts and how to define system sorts and user sorts, see Structured Sorts.
Specify the Level of Security Debugging Information 
CA Live API Creator
 Sends
You can specify the level of debugging information API Server sends API callers, including why the security layer behaves the way it does. By default, 
CA Live API Creator
 does not send API callers debugging information. The value for the 
Provide detailed security debugging
 field that is on the 
Settings
 tab is zero ('0'). You can specify a value between zero ('0') and five ('5'). Values one ('1') to five ('5') provide increasing levels of debugging information. Security debugging information can be useful during development and debugging, but might not be as useful in production.
For more information about this option, see the context help.
Specify the String to Emit in for Positive Infinity Values
You can specify the string that you want API Server to emit in for positive infinity values by selecting the 
JSON Positive Infinity
 option that is on the 
Settings
 tab. By default, the string value that is emitted is null.
For more information about this option, see the context help.
Specify the String to Emit in for Negative Infinity Values
You can specify the string that you want API Server to emit in for negative infinity values by adding it to the 
JSON Negative Infinity
 option that is on the 
Settings
 tab. By default, the string value that is emitted is null.
For more information about this option, see the context help.
Specify the String to Emit in for Quiet Not a Number Values
You can specify the string that you want API Server to emit in for quiet not a number (NaN) values by adding it to the 
JSON NaN (Quiet)
 option that is on the 
Settings
 tab. By default, the string value that is emitted is null.
For more information:
Specify the String to Emit in for Signaling Not a Number Values
You can specify the string that you want API Server to emit in for signaling Not a Number (NaN) values by adding it to the 
JSON NaN (Signaling)
 option that is on the 
Settings
 tab. By default, the string value that is emitted is null.
For more information:
Binary Output Encoding
The JSON response format can return binary data as either Base64 or HEX. You can choose the encoding scheme for your API from the 
Binary Output Encoding
 option that is on the 
Settings
 tab.
Options:
 
  • hex.
     A HEX string. HEX string format returns values beginning with '0x'.
  • Base64. 
    A Base64-encoded string of values. Base64 string format returns values beginning with 'b64'.
Default:
 hex
For more information about how API Creator emits binary data, see Use Binary Data and the context help.
Force Binary Data as an Object
When emitting binary data, you can force API Server to return binary data as an object instead of inline. To force the output to be an object, select the 
Force Binary Data as an Object
 checkbox that is on the 
Settings
 tab. By default, this checkbox is cleared. If the output is larger than the value you set in the 
Inline Limit Default
 field that is on the 
Settings
 tab, then the output is always an object.
Default:
 2000 bytes
For more information about this option, see the context help.
Force Consistent Pagination
When retrieving data, you can ensure proper pagination by appending the primary key to any pre-existing ordering. Databases guarantee the order of records that are retrieved only when there is an order-by. You can force consistent pagination when a primary key is not provided by selecting the 
Force Consistent Pagination when no primary key
 checkbox that on the 
Settings
 tab.
For more information about this option, see the inline help.
Modify the Root Element Tag Name
You can modify the Root Element tag name by entering a tag name in the 
XML Document Root Element Tag Name
 field that is on the 
Settings
 tab.
Default:
 root
Enable your API for Basic Authentication
By default, your API generates authentication tokens. You can choose for your API to not generate authentication tokens by clearing the 
Enable HTTP Basic Authentication
 checkbox that is on the 
Settings
 tab. When this checkbox is selected, you must enter a value for the 
Realm for HTTP Basic Authentication
 field that is on the 
Settings
 tab
HTTP basic authentication is not a secure process. Consider keeping this default setting only if you are using Secure Sockets Layer (SSL)/Transport Layer Security (TLS).
For more information about this best practice and other security best practices, see Securing APIs.
Default:
 Selected
If you are migrating (or upgrading) 
CA Live API Creator
 to a newer version, this checkbox is cleared for your existing APIs.
For more information about this field, see the inline help.
Define the Realm in the WWW-Authenticate Challenge Response
When your API is enabled for basic authentication (the 
Enable HTTP Basic Authentication
 field is selected), enter the realm in the WWW-Authenticate Challenge response in the 
Realm for HTTP Basic Authentication
 field that is on the 
Settings
 tab.
For more information about this field, see the inline help.
Display In-Memory Logs
By default, API Creator displays the in-memory logs for your API, such as detail transaction information, as log entries on the Logs page. You can choose to have API Creator not display these logs by clearing the 
Enable In-Memory Logs
 checkbox that is on the 
Settings
 tab.
Default:
 Selected
Best Practice:
 Turn off in-memory logging at the server level, especially in test and production environments, and configure external logging.
For more information about this installation best practice and the other installation best practices, see Installation Best Practices.
For more information about this field, see the inline help.
Verify your API
You can generate a list of issues that represent potential problems with the schema, the rules, or other findings. You can explore the issues and fix them one by one.
For more information about how to view the list of API issues, see Manage API Issues.
Follow these steps:
 
  1. In the Create section, click 
    API Properties
    .
    The 
    Overview
     tab appears.
  2. Click 
    Verify
    .
Your API is verified.
Delete your API
Deleting your API deletes the rules and resources that are associated with your API.
Best Practice:
 Before deleting your API, back up your API.
You can have your server back up what is in memory by adding an option at startup.
For more information about this installation option, see API Server Startup Options.
If you are managing tables, fields, and relationships in a data source for a managed database, deleting your API does not delete the managed database.
Follow these steps:
 
  1. In the Create section, click 
    API Properties
    .
    The 
    Overview
     tab appears.
  2. Click 
    Delete
    .
Your API is deleted.