CA Live API Creator 3.2

5.4 5.3 5.2 5.1 5.0 4.1 4.0 3.2 3.1.1 3.1
English

API Properties

As an administrator, you can control the API details and define the individual API attributes.
lac31
As an administrator, you can control the API details and define the individual API attributes.
In this article:
Control the API Details
  1. In the Create section, click 
    API Properties
    , 
    Details
    .
  2. You control the details by defining the following:
    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.
    API is enabled
     
    Defines whether your API is enabled or disabled. Enabled APIs can accept incoming requests. Disabled APIs are blocked from incoming requests.
    Default:
     Selected
    Authentication provider
     
    Specifies your authentication provider. Clients access the REST API for your API using an auth token. But often you might want users to use a name/password combination to authenticate.
    Default value:
     Built-in authentication
    Options:
     
    • Built-in authentication - API Creator includes this authentication provider to simplify development, is intended mainly for development, and is selected by default. Choose this option if you want to define users and passwords and convert a set of credentials (typically user name and password) into a usable auth token using REST.
      For more information about how to manage users using the built-in authentication provider, see Manage Users using the Built-in Authentication Provider.
    • None - Choose this option if you plan to use auth tokens directly.
    • Custom authentication provider.
      Prerequisite:
       You have created your custom authentication provider.
      For more information about how to create a custom authentication providers, see Create Custom Authentication Providers using JavaScript.
    For more information about how to specify your authentication provider, see Specify your Authentication Provider.
  3. Save your changes.
The details for your API are saved.
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.
In the Create section, click 
API Properties
, 
Verify
.
For more information about how to view the list of API issues, see Generate a List of API Issues.
Delete your API
Deleting your API deletes the rules and resources associated with your API.
 
Prerequisite:
 Create a backup of your API by exporting it. For more information about how to export your API, see Import and Export APIs.
 If you have a managed database, deleting your API does not delete the managed database.
In the Create section, click 
API Properties
, 
Delete
.
Define the API Settings
You can define individual API attributes using the fields on the Settings page. To view this page, in the Create section, click 
API Properties
, 
Settings
.
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 by selecting the 
Aggregate Default Override
 checkbox. By default, aggregates (such as sums and counts) are initialized to zero ('0') on insert, regardless of the client-supplied value. Select this checkbox to throw exceptions when you attempt to update aggregate values.
For more information about ignoring client attempts to update aggregate values, including how to change the JSON object
@metadata
 section name, see Manage your API.
Allow All API Calls using HTTP and HTTPS
You can allow all API calls using HTTP and HTTPS by clearing the 
HTTPS only
 checkbox. By default, all API calls are allowed. If security is not a major concern for your API, then allow all API calls using HTTP or HTTPS.
 Allowing all API calls does not guarantee that the caller used HTTPS. Due to issues related to firewalls and load balancers, a caller can fake this. To force API calls to use HTTPS, turn off the HTTP endpoint on your web server(s) (though even that may still not be a complete guarantee). This is a general HTTP issue.
Change JSON Object @metadata Section Name
 
CA Live API Creator
 returns JSON objects that includes the 
@metadata
 section. In some environments, this name can be a problem. You can change the section name for your API by entering a unique value in the 
Metadata name
 field. Choose a name that is unlikely to clash with a column name or a resource attribute name. For example, __metadata__.
For more information about how to use the JSON object, see JavaScript.
Define the Number of Characters or Bytes used to Calculate Checksum
You can define the number of characters or bytes used to calculate the checksum using the 
Checksum Size Limit
 field. If the column is larger than this setting, the checksum is computed using the total size and the checksum of the first n bytes/characters, where n is the value you define in this field. This is unrelated to the value format (
inline
 or 
deferred
) returned and can be larger or smaller that 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.
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 Normal 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 5000.
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 Subresource Rows
You can control the number of queries that 
CA Live API Creator
 executes to return the rows for 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.
Stored Procedure Row Limit
You can define the maximum number of rows that 
CA Live API Creator
 returns for each result set returned by a stored procedure using the 
Stored Procedure Row Limit
 field. Result sets are not pageable. This value is a value in the JSON telling you the limit was exceeded.
Stored Procedure Inline Limit
The values that 
CA Live API Creator
 returns in a stored procedure determine when it inlines using the value that you set for the 
Stored Procedure Row Limit
 field. You cannot generate URLs for 
deferred
 links. When a value exceeds the value set in this field, 
CA Live API Creator
 returns the length.
Permit Authorization Parameter in URLs
You can authorize API users to specify their auth token on the URL using the following format by selecting the 
Permit Authorization parameter in URL
 checkbox:
…&auth=123456789:1
By default, this checkbox is cleared. When selected, you can retrieve the contents of BLOBs from an HTML document using an href. Select this API property setting if users want to make GET requests straight from a browser or if, for whatever reason, they cannot set HTTP headers. (POST/PUT/DELETE also support this, but typically this is not useful.)
Authorizing users to specify their auth token on the URL has security implications. Browsers can remember URLs and URLs are typically logged in servers, routers, etc.
Specify URLs for Documentation
You can specify URLs for documentation. Specify the URLs in the 
Tech docs URL
 and 
User docs URL
 fields. The links must be HTTPS (for example, you can designate Google Sites).
Globally Describe the Expected Response Format
You can change the expected response format globally across an API.
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.
  1. In the Create section, click 
    API Properties
    , 
    Settings
    .
    The Settings page appears.
  2. Define the following field and save your changes:
     
    Default response format
     
    Select a value from the drop-down.
     
    Options:
     
    •  
      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 returned, putting the returned records in a nested "data" attribute.
    •  
      xml.
      Restructures metadata into XML tag attributes.
     
    Default:
     json
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. Allowing the discovery of the API Swagger doc without authentication is useful. Many Swagger consumers do not support authentication (even though the Swagger "standard" itself does). If you must connect your API to such a Swagger consumer, 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 User Audit Transaction Services
You can enable tracking and persistence of audit logs for all PUT, POST, DELETE transactions written to the 
userTxAudit
 admin database by selecting the 
Audit User Transactions
 checkbox. You can have API Server write to Mongo after persistence to the 
userTxAudit
admin database by creating a resource named 
_USER_TX_AUDIT_
 that points to the MongoDB server.
For more information about MongoDB integration, see Define MongoDB Resource Types.
Turn off Regular Filters
To turn off regular filters, select the 
Disallow free-form filters and sorts
 checkbox. By default, this checkbox is cleared. When regular filters are turned off and a request specifies a filter in the URL, the request fails.
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.
  • About this option, see the context help.
Specify the Level of Security Debugging Information 
CA Live API Creator
 Sends
You can specify the level of debugging information 
CA Live API Creator
 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 and the value for the 
Provide detailed security debugging
 field 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 is 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
Specify the string to emit in for positive infinity values by selecting the 
JSON Positive Infinity
 option. 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
The 
JSON Negative Infinity
 option specifies the string to emit in for negative infinity values. 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
The 
JSON NaN (Quiet)
 option specifies the string to emit in for quiet not a number (NaN) values. 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
The 
JSON NaN (Signaling)
 option specifies the string to emit in for signaling NaN values. 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 using the 
Binary Output Encoding
 option.
 
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 Creator to return binary data as an object instead of inline. Select the 
Force Binary Data as an Object
 checkbox to force the output to be an object. By default, this checkbox is cleared. If the output is larger than the value you set in the 
Inline Limit Default
 field (by default, 2000 bytes), then the output is always an object.
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 provide a guarantee of the order of records 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.
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.
 
Default:
 root
Enable your API for Basic Authentication
You can enable your API to generate auth tokens by selecting the 
Enable HTTP Basic Authentication
 checkbox.
 
Default:
 Selected
 HTTP Basic Authentication is not considered a secure process. We recommend enabling it only if you are using SSL/TLS.
 When you create an API, this checkbox is selected by default. If you are upgrading 
CA Live API Creator
, 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 HTTP Basic Authentication is enabled for an API, enter the realm in the WWW-Authenticate Challenge response in the 
Realm for HTTP Basic Authentication
 field.
For more information about this field, see the inline help.
View the Audit Trail of Changes
As you apply changes to your API, you can view an audit trail of the changes you make.
In the Create section, click 
API Properties
, 
Latest changes
.
For more information about viewing this audit trail of changes, see Change Management.