Getting Started‎ > ‎

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 API Creator. Activation is instantaneous. There is no code generation or deployment.

Data Explorer is created from the schema. Test your API and perform back-office database maintenance using this component.

For more information about Data Explorer, see Data Explorer.

Admin Database

Live API Creator stores your datasource connections, resource definitions, logic, and security settings in API Server's Admin database. The Admin database is transparent for cloud/appliance users and Web application ARchive (WAR) users must configure it. You can export admin contents into a file for maintenance in a source control system.

You can access and manage the admin data stored in the Admin database by way of the Admin API, which is a RESTful APIYou can script the creation of APIs into an API Server using the Admin Command Line Interface (CLI).

For more information about how to script the creation of APIs, see API Creation by Command Line.

Declarative Services

Customize your API, integrate additional data sources, and specify your logic and security policy using the following declarative services:

  • Retrieval. Live API Creator provides RESTful listeners, SQL processing, and JSON request/response processing for all endpoints.
  • Update-logic execution. Live API Creator enforces your reactive logic on all PUT, POST, and DELETE requests. This applies to updates, to custom resources, and to tables.
  • Data-security enforcement. Live API Creator control row/column retrieval and on updates by applying role permissions on GET.
For more information:

JavaScript Extension Points

You can call legacy logic, and other packages, using the following JavaScript extension points:

  • Events. Use events for requests, GET operations (for example, 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 JavaScript object model. This object model reads and writes data by addressing attribute/object accessors and persistence services.
  • 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

Live API Creator provides transparency with debugging services, including a log of all logic/database operations and a REST Lab so you can test your APIs without having to write a test program. You can test your logic using Data Explorer.

For more information about debugging, see Debugging.

Team Development

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

For more information:

Change Management

You can protect client applications from changes in logic, security, and the database using custom resources.

For more information about change management, see Change Management.

Life Cycle Management

You can access the Admin database using REST APIs. You can script the API-to-API-server deployment from source control artifacts. For example, you can save development artifacts and export admin contents into a file for maintenance into a source control system (such as the export artifact). You can script the creation of APIs into an API server into a production system using the Admin CLI.

For more information:

Documentation

Documentation services include:

  • API documentation, by way of Swagger.
  • System documentation, by way of URLs you can associate with your API project and view in API Creator.
  • Logic documentation, by way of 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 (Apache Tomcat, Jetty, application servers). You can load-balance the servers using standard technology. API definitions do not result in code generation. Deployment of a running system (for example, 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. You can export an API and script the import/export procedure using the Admin API.

For more information about scripting the import/export procedure, including exporting an API to a JSON file and importing the JSON file on a target system, see Import and Export API Definitions.

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. You can get meaningfully improved re-use and reduced development time using the services for client app development. 

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. Invoke stored procedures directly using JavaScript events.

Existing Systems

API Server connects well to existing databases for retrieval, with the following caveat. Some systems define new columns without schema changes by storing data as Binary Large OBjects (BLOBs), for example, XML or JSON data. This practice hides the columns to SQL, to other software such as business intelligence, and to API Creator.

For updates, API Server, like any RESTful server, operates in a standard three-tiered architecture. It is analogous to an application server, accessed by way of RESTful APIs rather than technology specific access such as J2EE. Like application servers, this architecture 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.

Like application servers, you need to be aware of applications that access the data directly without going through the APIs. Direct-data access does not enforce the logic and security that API Creator defines. Conversely, if you have existing systems that already enforce your logic, you must work within that context using API Creator.

The following scenarios are included:

  • Read Only. In the simplest case, update logic is not an issue if you are just reading data.
  • Update considerations. The following are common scenarios for update:
    • Triggers. If you are using database triggers, triggers fire as API Server issues SQL updates.
    • Stored procedures. You can invoke store procedures from JavaScript (for example, from Table Events), using the connection made available by API Server.
    • External logic. Logic is sometimes externalized in application servers (for example, as or bound into an 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 this logic is typically not available outside the screen. We recommend that you migrate the screen logic to a shared server such as Live API Creator.
You can create new sub-systems (manage new data that interact with existing data) and integrate systems through RESTful message exchange using Live API Creator.

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

App Server

JavaScript extensions are useful in integrating existing systems and logic, such as application servers. For example, you might use row events to acquire data from application servers or data integration servers.

Security Systems

Live API Creator provides authentication for development. Production systems typically use existing corporate security systems, such as Lightweight Directory Access Protocol (LDAP), Active Directory (AD), or OAuth, by delegating authentication. 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.

For more information about authentication, see Authentication.

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.

Rules Engine

Live API Creator logic is complementary to other automation services, such as a rules engine for decisions and workflow.

Enterprise Service Bus

Service orchestration products (also known as Integration Platform as a Service (iPaaS), such as MuleSoft), can provide enterprise integration by assisting in building an enterprise service bus that integrates a number of existing underlying REST services. 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

Your API can consist of schema resources, or endpoints, system resources, or custom resources. Your schema resources are defaulted from the schema. System resources are automatically-created metadata services to obtain the list of tables and resources and their attributes. Custom resources are the endpoints you define explicitly.

Expose Tables and Stored Procedures as Resource Endpoints

You can can expose your base tables, view tables, and stored procedures as resources, or resource endpoints. Resources are available instantly. There is no restart, code generation, deploy, or configuration. After you have exposed the tables and procedures, you can begin browsing your API and start app development. You can protect access to this data by turning this off later in the API project.

For more information:

Access Resource Endpoints 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 the following 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 (for example, payments, purchase orders, line items, and product information). You can also use the other retrieval services.

For more information:

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. Sub-resource rows are retrieved in the same request, with optimizations for multi-database resources. All of the sub-resource rows are retrieved in one query.

For example, you have a pagesize of 10, retrieving customers and their orders. On the first request, API Server does the following:

  1. Retrieves the first 10 customers.
  2. Extracts the 10 customer keys and performs a query for orders with a where clause for all 10 customers ("cust-1 or cust-2, ...') using these keys. The query also includes relevant security filters.
  3. Distributes the orders to the proper customer in the preparation of the JSON response.

This avoids 10 orders queries and performs well in multi-database configurations where a customer-join-order is not feasible.

Note: You can control the chunk size on a per-request basis. For example, you can emit the simple SQL for debugging and testing by setting the chunk size to one (1).

For more information about controlling chunk size, see API Properties.

Security

Your security specifications are defined for base tables and are applied automatically to all resources defined over that table. You can specify the security properties after you define your resource.

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.

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 show derivation results by re-retrieving data.

Performance

Per REST requirements and industry best practice, all processing is stateless. Live API Creator scales horizontally. A number of services address enterprise-class performance, such as reduced network latency, through RESTful server operation, to DBMS optimization.

For more information about the services that address performance, see Performance.