Docs‎ > ‎CA Live API Creator‎ > ‎

API

Each API Project represents the grouping of your database connections, schema, resource endpoints,  business rules and events as well as the security access-control settings.  

We also refer to a Project as an API.

This page describes how to use the Logic Designer to create and manage projects.


Multiple API Projects per Account

API Creator manages one or more APIs.  These APIs are all active and available (i.e. "running").  The API Creator allows you manage the contents of the current API.  



Choosing an API Project

Choose the current project using the combo box at the menu bar located on top-center of the Logic Designer.

OR - you can click the Home and see a series of tiles - each will represent an API Project.


Creating A New API Project

There are two alternatives for creating a project.

Creating an API Project from the Navigation Menu

The simplest way to create a project is via the Home New API Button.   This will launch the Create Database Dialog Wizard.


API Project Properties Checklist

For proper operation of your project, please ensure the following are properly defined:
  • Database Settings for your Active Database
  • Security settings (see especially Dev vs. App User) for the Authentication Provider
  • Project Libraries and other Project Attributes 

Active Database

Each project has a list of one or more registered databases (see Datsources).  This list may have only 1 entry (created as part of a New API project creation, as described above), or many databases.  Multiple entries are enable you to use your service for test databases, integration databases, the production database, etc. 


The sub-sections below described the key attributes of a project.  Use Short Menus; note some of these are included under the tab sheets.

API Properties - Details Tab


API Name

The identifies your API project, set when you create your project.  This is your internal name.

URL Fragment

The URL for your project's API is composed of several parts, one of which is specific to the project. That's the URL fragment. It should be (usually) short, and contain only characters that are valid in a URL. If you use characters that are invalid, they will be automatically replaced with underscores.
Project URL names must be unique within your account.

Authentication Provider

The Authentication Provider authenticates that login credentials (typically a user / password) are correct, and returns a set of roles.  You can supply your own provider to utilize corporate security services, or use the provided default.  Sample Authentication Providers are available from GitHub for Windows Azure AD,SQL LDAP, and more.

API is Enabled

If this checkbox is not selected, then this API is considered disabled. A disabled API cannot be used until it is marked as enabled. This is useful if you need to take an API offline for some reason.


Export Button 

The Projects page has a button to Export the current selected project as a file download.  This export contains all the meta data for the current project including, database schema, business rules, resource endpoints, security definitions for users and roles. The export produces a .JSON file which can be saved into a source control system or used to import into another account.


IMPORTANT : for security reasons, the JSON export does not save certain information.  So, after the Project Import is completed: 
  • re-specify you database password
  • specify user passwords (if you are using the default Authentication Provider)
  • re-specify your Authentication Provider on the API Properties  dialog
  • optionally, you may also want to re-specify the Project URL (which will include the timestamp of the import)
See the Logic Sample Project for screen shots and details.


Import Button

This button imports a exported project as described above.  See also here.


Verify Button

API Creator does not replicate your schema. You are free to use your existing tools to manage your schema. 
The API Creator rule repository does, of course, make reference to schema objects such as table and column names. If these are dropped or renamed, you need to synchronize these with your repository. The project Verify button will re-validate the schema with the rules definitions and show problems on the 'Issues' tab in Logic Designer. 


So, API Creator provides the following services to help you manage repository / schema. Please see Database Administration


Setting Tab

( a partial list of these settings)

Aggregate Default Override

This setting authorizes the system to ignore client attempts to update aggregate (sum, count, min, max) values.  False means exceptions are thrown on such update attempts.

Type Base URI

This will be used in a future release and should be ignored for now.

HTTPS Only

If this option is set to "true" (without the quotes), then only HTTPS API calls are allowed. This is the case by default. If security is not a major concern for your project, you can turn set this to false, which will allow calls using HTTP or HTTPS.

Metadata Name

In the JSON objects that get returned by Live API Creator, there is a special section which, by default, is called @metadata. In some environments, this name may be a problem. Using this option, you can change this to a different name that works better for your project.
The name you choose (if you decide to use this option) should be unique enough that it is highly unlikely to clash with a column name or a resource attribute name. Something like __metadata__would be typical.

Allow Swagger without authentication

If this option is set to true, then the Swagger schema can be retrieved without authentication.
This is useful because many Swagger consumers do not support authentication (even though theSwagger "standard" itself does).
The Swagger schema can be retrieved at a URL that looks something like:

https://myserver.acme.com/rest/acme/proj1/v1/@docs

If you need to connect your API to such a Swagger consumer, you can enable this option temporarily, then turn it off once the API has been retrieved.

Disallow free-form filter

When you need maximum flexibility in filtering your data, you can use regular filters, e.g.:

.../rest/acme/myproj/v1/Customer?filter=balance<1000

There is, however, a serious problem with regular filters: they aren't safe. This is because a regular filter is basically a piece of SQL code that gets sent directly to the database. In most cases, that's fine, but this mechanism can be used by malicious persons to access data they're not supposed to have access to.

That's called a SQL injection, and it's a frequent cause of unintentional data leaks. Regular filters should be thought of as a prototyping tool: they're quite nice when you want to move fast, but not appropriate for production systems. So, if security is a concern, you need to turn off regular filters by checking this option. Once you do so, any request that specifies a filter in the URL will fail.

Libraries Tab

This is a list of Java and JavaScript libraries for your project. If you would like to use one or more of these in your JavaScript logic, you can select them here.

For example, many projects will use date arithmetic, so would select the Moment Library.

You should not select any libraries that you do not in fact use, since there is a (small) memory impact for every additional library selected.

New Libraries (JAR files) and JavaScript files may be uploaded using the 'Your Libraries' tab and the 'Create New Library' button.

Documentation

You can specify URLs for Documentation which will be shown in tabs on the Designer Home Page as shown here.  Specify the URLs in project settings.  The links must be https (e.g., Google Sites can be designated as such).

Topics Tab

While logic is automatically invoked for relevant transactions, it is very useful to capture business requirements, and the logic that implements them.  You can define Topics, and link them to logic.

Filters Tab

You can create predefined named filters that allow customized expressions that mask the internal column and SQL syntax.  See Structured Filters documentation.

Sorts Tab

You can create predefined named sort expressions.  See documentation for detail syntax. 

Latest Changes Tab

This is an audit of administration changes to the selected API project.