Docs‎ > ‎

Architecture

Live API Creator provides declarative definition of the following services:
  • API. Create the default API by connecting to your database: GET, POST, PUT, and DELETE for each table, including GET/POST access to each view and stored procedure. You can create nested document resources or endpoints.
  • Integration. Resources can combine data from multiple sources (SQL, Mongo, and RESTful), including updates between them.
  • Security. Enforces end-point access and row/column security.
  • Logic. Enforces database integrity on updates, with a combination of spreadsheet-like Rules and server-side JavaScript. Rules automate multi-table change detection/propagation and SQL handling, so are 40X more concise than conventional code.
   

Specify your settings in Live API Creator. Activation is instantaneous. There is no code generation or deployment.

The Data Explorer is created from the schema. Use this component to test your API and for back-office database maintenance. For more information about Data Explorer, see Data Explorer.

You can install the RESTful service and database in the cloud, on-premise, or in a WAR file. Use your existing database or the pre-supplied empty database in the Your Database project.

Declarative Services

Customize your API, integrate additional data sources, and specify your logic and security policy.

JavaScript Extension Points

You can call legacy logic, and other packages, using the JavaScript Extension points. Live API Creator includes the following basic entries into your JavaScript logic:
  • Events. Provided for requests, GET operations (e.g., call an external service, or an Application Server), and PUT/POST/DELETE operations. Events are server-side JavaScript-code business logic, based on the automatically-created Object Model - attribute/object accessors, and persistence services to read and write data.
For more information about events, see Logic Events.
  • Rules. Specify by filling out forms and providing JavaScript functions.
You can extend system automation for update and retrieval logic with procedural code using server-side JavaScript code. The JavaScript extension points are the basis of the extensibility services.

For more information:

Debugging

Transparency is provided with debugging services including a log of all logic/database operation, and a REST Lab so you can test your APIs without having to write a test program. You can test your logic with the Data Explorer.

Team Development

Multiple Developers can create APIs and logic concurrently. You can import/export your project into a JSON file, which you can manage with existing tools for diffs, Source Control Systems etc.

For more information about team development, see Team Development.

Change Management

Custom Resources can protect client applications from changes in logic, security and the database.

For more information about change management, see Change Management.

Life Cycle Management

The Admin database is accessible by REST APIs, so you can script the deployments of APIs to API Servers from Source Control artifacts. For example, you can save development artifacts into a Source Control system (such as the export, above), and script their deployment into a production system.

For more information a
bout viewing an example of how you can script the life cycle operations, see the Business to Business Example.

Documentation

Documentation services include:
  • API documentation, via Swagger.
  • System Documentation, via URLs you can associate with your project and view in the Designer.
  • Logic Documentation, via Topics that trace requirements to the rules that implement them.

Deployment

Live API Creator is delivered as a WAR file. You can deploy into standard containers (Tomcat, Jetty, App Servers). You can load-balance the servers using standard technology. API Definitions do not result in code generation. Your settings (datasource connections, resource definitions, logic and security) are stored into the admin database.

Deployment of a running system (e.g., deploying a test system into production) requires an admin database update (the API Creator WAR is not changed). You do this by exporting an API to a JSON file, which you can import on the target system. Manage the admin data by way of the Admin API. This enables you to export an API and script the import/export procedure.

Architectural Fit

Live API Creator fits into an enterprise architecture. The following are typical integrations:

Web/Mobile Apps

API Servers figure significantly in app development, ranging from basic connectivity, to object generation, to partitioning. Live API Creator provides a number of services for client app development, resulting in meaningfully improved re-use and reduced development time.

Databases

Access cloud/on-premises SQL databases by way of JDBC. Their tables, views, and stored procedures are valid endpoints, per security settings. Updates are subject to database logic, such as triggers. Use JavaScript events to invoke stored procedures directly.

Existing Systems

For retrieval, API Server connects well to existing databases, with the following caveat. Some systems that store data as blobs (e.g., xml or json data), often to define new columns without schema changes. This practice essentially hides the columns to sql, and other software such as Business Intelligence, etc. And to API Creator.

For updates, API Server (like any RESTful server) operates in a standard three-tiered architecture. It is analogous to an App Server, accessed by RESTful APIs rather than technology specific access such as J2EE. Like App Servers, such a tier can provide services for 
  • Integration. Your API can integrate data from multiple databases, and send/receive messages from other systems.
    For more information about viewing an example of integration, see the Business to Business Example.
  • Scalability. You can scale multiple API Servers under a Load Balancer for increased response and fail over
  • Logic and Security. API servers provide a modern approach to enforcing logic, instead of (for example) proprietary triggers. In the case of API Creator, the bulk of this logic is Reactive, using spreadsheet-like rules which are substantially more succinct than conventional code.
Like App Servers, you need to be aware of applications that access the data directly, without going through the APIs. Such access does not enforce the logic and security defined in API Creator.

Conversely, if you have existing systems that already enforce your logic, it's important to use API Creator to work within that context. There are several scenarios, including:
  • Read Only - in the simplest case, update logic is not an issue if you are just reading data
  • Update considerations - there are common scenarios for update:
    • Triggers. If you are using database triggers, these will naturally fire as the API Server issues SQL updates.
    • Stored Procedures. you can invoke these from JavaScript (for example, from Table Events), using the connection made available by the API Server
    • External Logic. Logic is sometimes externalized in Application Servers (for example, as or bound into a object access layer). Depending on how you architect them, they can be easy or difficult to call (for example, consider transaction boundaries).
    • Screen Logic. Often, external logic is bound into screen logic (for example, controllers attached to buttons). This is the 'fat client' ant-pattern, since such logic is typically not available outside the screen. We recommend that you migrate it to a shared server such as Live API Creator.
Live API Creator can provide significant value in creating new sub-systems (managing new data that interact with existing data), and integrating systems through RESTful message exchange.

To view an example, see the Business to Business Example.

App Server

JavaScript extensions are useful in integrating existing systems and logic, such as App Servers. For example, you might use Row Events to acquire data from Application Servers or Data Integration Servers.

Security Systems

Authentication is provided by default for development. Production systems typically delegate authentication to use existing corporate security systems, such as LDAP, AD, or OAuth.

Live API Creator injects authorization at the row/column level into SQL that is sent to the database, where Live API Creator can properly optimize authorization.

API Management

API Server is a standard REST API. You can insert API Management Systems (they operate as Gateways) for monitoring, denial of service attack protection, etc.

MBaaS/PaaS Services

Live API Creator can be an important component to your Mobile BackEnd as a Service (MBaaS), providing transaction processing automation to complement technologies such as push or security/social integration.

Rule Engines

Live API Creator logic is complementary to other automation services, such as rule engines for decisions and workflow.

Enterprise Service Bus

Service Orchestration (iPaaS) products (also known as Integration Platform as a Service, such as MuleSoft), can assist in building an Enterprise Service Bus that integrates a number of existing underlying REST services to provide Enterprise Integration. Live API Creator plays a complementary role by enabling you to build (and integrate) services that don't already exist. These run alongside existing manually coded database services, as well as non-transactional services that deal with more content-oriented information.

Resource Endpoints

Live API consists of resource endpoints which are defaulted from the schema, along with Custom Resources you define explicitly.

Expose Tables and Stored Procedures as Resource Endpoints

You can can expose all of your Base Tables, View Tables, and Stored Procedures as resource endpoints, or resources. After you have exposed the tables and procedures, you can begin browsing your API and start app development. You can turn this off later in the API project to protect access to this data.


For more information about explicitly defining custom resources, see Define Custom REST Resources.

Resources are available instantly. There is no restart, code generation, deploy, or configuration.

Access Resource Endpoint with a RESTful API

You can access your resource endpoints by way of a RESTful API. This makes your data available from virtually any client, in particularly mobile clients and cloud-based access. You can issue HTTP-based retrieval requests against these resources using a URL, for example:

http://eval.acme.com/account/project/apiversion/request

You can retrieve a single JSON object (in this case a Customer with key = Acme), for example:

GET http://.../rest/v1/cust/Acme

Your program can also issue retrieval operations against these Resources, for example:

GET http://.../rest/v1/cust?filter=name%3C%27Shar%27&order=name%20desc,balance

The filter controls what "cust" resource rows are returned in a JSON array, sorted per the order clause. You can omit the filter, in which case all the customers are returned in an array.

Each customer is returned as a JSON string, including its nested objects (e.g., payments, purchase orders, line items, and product information). You can also use the other retrieval services.

For more information about retrieval operations, see Language Examples.

Enterprise-class Services

The following services are provided for enterprise-class use:

Coalesced Retrieval Strategy

Retrieval is processed a level at a time, retrieving <pagesize> rows per request. SubResource rows are retrieved in the same request, with optimizations for multi-database resources: all of the SubResource rows are retrieved in one query.

For example, imagine we have a pagesize of 10, retrieving customers and their orders. On the first request:

      • The first 10 customers are retrieved
      • The system extracts the 10 customer keys, and uses these to perform 1 query for orders with a where clause for all 10 customers ("cust-1 or cust-2, ...'). The actual query also includes relevant security filters.
      • The system distributes the orders to the proper customer in the preparation of the JSON response.
Observe this avoids ten orders queries, so performs well in multi-database configurations where a customer-join-order is not feasible. Each project has a default 'Chunk Size' to control this behavior. You can set chunk size to one to emit the simple SQL for debugging and testing and can even be changed on a per request basis.

Security

Your security specifications are defined for base tables, and are automatically applied to all Resources defined over that table. You can specify the security properties after the Resource(s) are defined.

For more information about defining your security definitions, see Security.

Pagination

Large result sets can cripple performance, both on the client and the server. You can retrieve more data using the URI that Live API Creator supplies. Pagination is supported at any sub-resource level. For example, a query of Customers and Orders can provide pagination for many customers and many orders for each of the customers.

For more information about performance and pagination, see Performance.

Reactive Logic

In the context of Live API Creator, business logic refers to the transactional logic that API Creator applies when committing a transaction.

For more information:

JavaScript Logic

Live API Creator creates JavaScript objects, or rows, for each Base Table. The rows provide accessors for attributes and related data, and automated persistence. Old/New versions of rows are supplied to your Events and Logic, with automatic Resource/Object Mapping.

For more information:

Reactive Programming Logic

Your logic specifications are defined for base tables and are automatically applied to all resources defined over that table. Logic execution is a sophisticated process that automates complex multi-table dependencies with automatic re-use across Use Cases, while maintaining enterprise-class performance through SQL reduction/elimination. Logic plans reflect the latest deployed logic, so that compliance and performance are maintained while providing business agility.

For more information:
  • About reactive programming, see Reactive Logic.
  • About logic execution, including how Live API Creator executes the business logic in response to REST POST/PUT/DELETE requests, see Logic Execution.
  • About business logic reuse, see Business Rules.
  • About how Live API Creator delivers enterprise-class performance, see Performance.

Derivations and Validations

Logic declared in the API Creator is bound to your database tables and enforced on all updates against those tables. Such injection provides automatic reuse. You specify the logic as a series of Constraint Declarations. Constraints are expressions that the runtime system will guarantee to be true for a transaction to succeed.

There are two basic types of constraints:

      • Derivations. Reactive Programming Expressions define the value of a column in a table. They range from simple formulas (product_price * qty_ordered) to multi-table (sum example). The key idea is that the system will watch for changes in referenced data; if detected, it will recompute the derivation in an optimal manner. This can become quite complex, since derivations can chain as in the example shown here.
      • Validations. These are expressions that must be true for a transaction to commit (else an exception is raised). Validations are multi-field, and can operate on derivation results (as in this credit_limit example).

Logic Example

The logic declared above, conceived to address Place Order, is automatically re-used over all related Use Cases. Such active enforcement is automatic (it does not rely on explicit programming calls), and therefore ensures compliance.

Let's consider one example: changing an Items qtyOrdered. The diagram at right shows how the system recomputes the price, amount, order amount, and customer balance.

While a small example, such automated multi-table dependencies, automatically re-used over multiple Use Cases, addresses the key challenge for transactional business logic.

JSON Refresh Information

A key benefit of logic is automated multi-table derivations. For example, saving an order might update the customer's balance. It is further possible (but not required) that this related data might be on the user's screen. Good user interface design dictates these effects be shown to the end user.

Live API Creator returns JSON refresh information for all updated data per logic execution,so that clients can merge these updates into the screen. This can improve performance since the client does not need to re-retrieve data to show derivation results.

Locking

Good performance dictates that data not be locked on retrieval. Concurrency is typically addressed by optimistic locking. Live API Creator automates optimistic locking for all transactions. This can be based on a configured time-stamp column, or, if there is none, a hash of all resource attributes.

For more information about optimistic locking, see Performance.

Transaction bracketing is automatic. PUT/POST/DELETE requests (which may be comprised of multiple roles) are automatically bundled into a transaction, including all logic-triggered updates.

Generated Key Handling

Typical application's logic often includes significant logic to handle DBMS-generated keys. For example, you want to add an order and line Items in one transaction. The Order# is generated into the database and Live API Creator places the key into each line item.

For more information about how primary keys are generated , see Generated Key Handling.

Performance

Per REST requirements and industry best practice, all processing is stateless. Live API Creator scales horizontally. Enterprise-class performance is addressed by a number of services described here, addressing performance from reduced network latency, through RESTful server operation, to DBMS optimization.