Managing APIs‎ > ‎

API Properties

API Project Details

As an administrator, you can control the API details on the Create, API Properties, Details tab. You control the details by defining the following:

  • The URL fragment.
  • The API project name (internal).
The API project name is the name by which you refer to this API. This field is free-form and should be a name that is meaningful to you. For example, Sales data or Accounts Receivable.
  • The API's authentication provider, the internal libraries, and the attribute settings.

Enable or Disable API Projects

Enabled APIs can accept incoming requests. Disable an API by clearing the API is enabled checkbox on the Create, API Properties, Details tab. This checkbox is selected by default. Disabled APIs are blocked from incoming requests.

Specify your Authentication Provider

Prerequisite: (If you are using a custom authentication provider) You have created your custom authentication provider.

Choose an authentication provider from the Authentication provider field on the Create, API Properties, Details tab.

Default value: Built-in authentication

Options:

  • Built-in authentication

To simplify development, API Creator includes an authentication provider that is selected by default. This authentication provider is intended mainly for development. It defines users and passwords and a service to convert a set of credentials into a usable auth token.

For more information about authentication, see Authentication and Authentication Providers.

  • None

If you plan to use auth tokens directly, choose None as the authentication provider.

  • Custom authentication provider

For more information:

Set the ident Value

Set the ident value for your API using the URL fragment field on the Create, API Properties, Details tab. The URL fragment is used in the API URL.

For more information about this field, see the inline help.

Delete your API

Deleting your API deletes all of the rules and resources associated with the API. Delete you API by clicking Delete on the Create, API Properties, Details tab.

Important!  If you have a managed database, deleting your API does not delete the managed database.

For more information about managed databases, see Managed Server Administration.

API Project Settings

You can define individual API attributes using the fields on the Create, API Properties, Settings tab. The following image shows the Create, API Properties, Settings tab:

For more information about fields on this tab, see the context help.

Ignore Client Attempts to Update Aggregate Values

You can authorize 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.

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.

Note: 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

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) using Inline Limit Default field.

For more information:

  • About the inlinelimit query parameter, see BLOB, CLOB, Large Strings, Large Binary.
  • 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 Binary Data and the context help. 

Control the Number of Rows Returned

You can configure pagination on large result sets that API Server returns. You can control the number of rows returned by default per batch by defining the value for the Page Size Default API property setting. You can override this setting on per-GET request basis.

For more information about pagination, including overriding the default on a per-GET request basis, see Pagination.

Control the Chunk Size

You can control the chunk size using the Chunk Size Default option on the Create, API Properties, Settings tab.

Stored Procedure Row Limit

You can define the maximum number of rows returned for each result set returned by a stored procedure using the Stored Procedure Row Limit field. Result sets are not pageable. This is a value in the JSON telling you the limit was exceeded.

Stored Procedure Inline Limit

Values returned in a stored procedure determine when to inline using the value you set for the Stored Procedure Row Limit field. 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 URL

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 normally this is not useful.)

Important! Selecting this checkbox 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. On the Create, API Properties, Settings tab, select a value for Default response format 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

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. Allowing the discovery of the API Swagger doc without authentication is useful because many Swagger consumers do not support authentication (even though the Swagger "standard" itself does).

If you need to 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. If you create a resource named _USER_TX_AUDIT_ that points to the MongoDB server, then API Server will also write to Mongo after persistence to the admin database.

For more information about MongoDB integration, see MongoDB Integration.

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 you disallow free-form filters and sorts (regular filters are turned off) and a request specifies a filter in the URL, the request fails.

For more information:

  • About structured filters, including the difference between regular filters and structured filters, see Structured Filters.
  • About this option, see the context help.

Specify the Level of Security Debugging Information Live API Creator Sends

You can specify the level of debugging information Live API Creator sends API callers , including why the security layer behaves the way it does. By default, 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 may 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 using 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 not a number (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 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:

  • For more information about how to choose how API Creator emits binary data, see Binary Data and the context help.
  • About this option, see the context help.

Force Consistent Pagination when no primary key

When retrieving data, you can ensure proper pagination by appending the primary key to any pre-existing ordering. Databases do not provide a guarantee of the order of records retrieved unless 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 context help.

XML Document Root Element Tag Name

You can modify the Root Element tag name using API Property settings. By default, root is the XML Document Root Element Tag Name setting.

Define the Available Libraries

API Creator includes a standard set of libraries. Logic libraries are JavaScript files of re-usable solutions for patterns. The JavaScript libraries for your API are displayed on the Create, API Properties, Libraries, System libraries tab.

The first few libraries listed on the System libraries tab are selected and available by default. You cannot clear the Used checkbox for those libraries. You can make the other libraries listed available to JavaScript event programming and use them in JavaScript logic by selecting the Used checkbox for those librariesFor example, many APIs use date arithmetic. The Moment.js library is a JavaScript date library for parsing, validating, manipulating, and formatting dates. You can make this library available inside your API.

Best Practice: There is cost in CPU and memory associated with each library you make available. Select only those libraries your API will use.

You can also:

  • Add a user library to an API.
  • Add Java user libraries to Live API Creator.
For more information:
  • About how to add JavaScript user libraries to an API, including viewing an example of how to load the moment.js library, and how to add a Java user library to Live API Creator, see Logic Libraries.
  • About selecting JavaScript libraries, see Extensibility.

Add a JavaScript Library for your API Project

You can add only JavaScript libraries to your API in API Creator. After you have added a library to your API, you can use its facilities in your rules by invoking classes and methods directly from JavaScript.

For more information about how to use a library you add to your API and use its facilities in your rules by invoking classes and methods directly from JavaScript, see Logic Libraries.

Add User Filters or Named Structures

You can add a user filter or named structures that mask or hide the internal SQL and prevent using free-form filters (to prevent SQL Injection) on the Create, API Properties, Filters tab. You can also disallow free-form filters. For more information about disallowing free-form filters, see Manage your API Project.

The following image shows the Create, API Properties, Filters tab:

For more information about using user filters, including named filters, see Structured filters

Add Custom-Named Sort Objects

You can add custom-named sort objects that can be exposed as part of the resource or table and mask internal SQL data on the Create, API Properties, Sorts tab.

The following image shows the Create, API Properties, Sorts tab:

For more information about the Sorts tab, see Structured Sorts.

View the Audit Trail of Changes

As you apply changes to your API, you can view an audit trail of those changes on the Create, API Properties, Latest changes tab.

For more information about viewing this audit trail of changes, see Track Changes.

More Information

For more information: