Demo API Sample
The Demo API is a representative sample application that illustrates basic concepts. This API sample demonstrates how you can build and run modern systems for web/mobile applications data access or for data integration using .
lac42
The
Demo
API is a representative sample application that illustrates basic Layer7 Live API Creator
concepts. This API sample demonstrates how you can build and run modern systems for web/mobile applications data access or for data integration using Layer7 Live API Creator
.The
Demo
API sample is included with the single-user demonstration package of Layer7 Live API Creator
that is based on Jetty and with the Layer7 Live API Creator
Docker container installation. No additional steps are required to load this API.You can also load this API sample if you have installed
Layer7 Live API Creator
on another Java container. In this article:
3
Problem: Servers are Hard to Build, Particularly the Business Logic
REST/JSON servers are the accepted approach for mobile application access to integrated data. In a Java stack, you might need to use Jersey, Jackson, and/or Java Persistence API (JPA). These frameworks can reduce coding, but they are complex to build and time-consuming, particularly when you consider enterprise-class requirements like filtering, sorting, pagination, and optimistic locking.
And, adding business logic and security can add significant effort to your development. For example, you might want to
check credit,
not just for placing orders, but all the other user stories (such as change item, delete item, re-select product). The business logic requirements–expressed in the following five lines–are clear to IT and business users alike, yet require hundreds of lines of code to implement:- Validate balance < credit-limit, where
- Balance is derived as the sum of the unpaid order amounts, where
- Order amounts are the sum of Item amounts, where
- Item amounts are a discounted price * quantity, where
- Prices are obtained from Products
The following sections describe how to build REST APIs in
Layer7 Live API Creator
. This API provides a user interface (UI) that:- Accepts spreadsheet-like expressions that express what your data means, how it is computed, validated, including actions such as auditing and deep copy.
- Executes this spreadsheet-like logic on all RESTful update requests (PUT, POST, and DELETE).
Watch the Video
The following video demonstrates of how to build a simple REST API in under five minutes that would otherwise require weeks. The REST API accepts orders from partners, mobile applications, or web applications; processes the orders and the related requirements to change orders; and posts messages to specific suppliers' systems.
Database Schema
The following image shows the schema for the
Demo
API sample:
Solution
The sample solution uses a familiar problem–customer, PurchaseOrder, and LineItems–to introduce various concepts in
Layer7 Live API Creator
:- Provide a UI to access your data using the defined APIs using Data Explorer.For more information about Data Explorer, see Data Explorer.You can also build a UI using JavaScript/HTML5. For more information, see the JavaScript Sample Application.
Expose Database Entities as REST Resources
To build a REST server, create an API and connect to your database using API Creator, which automates the web service layer and data access.
Layer7 Live API Creator
automatically exposes the entities (tables and views) and stored procedures as REST endpoints. You can test the entities and stored procedures in the REST Lab without writing a program.For more information:
- About how to connect your API to your database, see Database Connectivity.
- About the system REST endpointsLayer7 Live API Creatorexposes, see System REST Endpoints.
- About how to test entities and stored procedures in the REST Lab, see Test your API Using the REST Lab.
Customize Multi-Table Resources
You can present related data within a single request by creating table-based resources. The following image shows related tables for the
Demo
API in API Creator:
You can:
- Define multi-level, table-based resources that deliver this data in a single JSON response, thereby minimizing the latency for your API. API Creator defaults the sub-resource join (Customers/Orders) from the foreign key validations.For more information about how to create table-based resources, see Define Table-Based Resource Types.
- Shape your API by specifying aliases for the attributes that are returned to the client.
- Define JavaScript resources by using your own code.
- Test your resources using the REST Lab.
Automation includes support for enterprise-class level services such as pagination, optimistic locking, and change summary information for client refresh.
For more information:
Business Logic Must be Addressed
The real work involves the business logic. Consider the Place Order user story or requirement. You might need to implement business logic for requirements such as the following:
- Check credit limit.
- Ensure that the balance cannot exceed the credit limit.
- Implement the logic for the balance, which is the sum of the unpaid purchase order totals.
- Implement the logic for the purchase order total, which is the sum of the Line Item amounts.
- Implement the line item amount as the derivation of quantity times the part's price.
Following that, you must identify the related use cases that must also adhere these rules. You must then design these rules for change detection, change propagation to dependent data, and optimization. Soon, the simple five-line specification becomes 500 lines of code. And yet, the requirements, as illustrated with the venerable cocktail napkin, were so simple. If only the requirements were executable.
Declare your Business Logic
Business logic requires domain-specific code, which can take up to approximately 500 lines of code. Writing the code can require weeks of work to build and test the dependencies. That is not fast, and it is not simple. What if, instead of programming your server for each use case/dependency, you could simply enter the requirements from the cocktail napkin? Entering the requirements from the cocktail napkin would be simple and fast in
Layer7 Live API Creator
.You can chain multi-table derivation logic, such as the customers' balance, use them in related logic. The
Check Credit
topic groups five rules in the Demo
API. The validation rule on the customer's balance (see demo:Customer
table) enforces the credit limit check, which in turn uses the the purchase order's amount_total
result to compute the customer's balance
.Layer7 Live API Creator
eliminates and simplifies SQL access by optimizing the derivations.For more information about exploring logic, see Logic.
Define the Security for your API
To secure your API, you require fine-grained security down to the row and column instance. You can define one or more roles for a user. You can associate roles data rows in your database and can use their column values to filter queries against other tables.
The following image shows the
My Orders - no update of paid flag
entity permission for the PurchaseOrder
table:
Define Table-Based Permissions
You can filter orders for a sales rep role to only return the purchase orders that are assigned to them, without the ability to alter the paid flag.
For more information about how to set entity-level permissions for roles, see Authorization and Role-Based Endpoint Access.
Define Row Filtering Based on User Table Value using Global
The
employee
object has a unique key on employee_id
. In this example, we want to use the employee values to filter rows in other tables. In this example, we want to filter purchaseorders
whose salesep_id
matches the employee_id
of the currently logged in employee.You define a a global (
current_employee_row
) for the SalesRep
role to obtain the currently logged in employee row. The predicate refers to the global using the @{<globalName>.<globalAttribute>}
syntax. When an API user assigned the SalesRep
role accesses the predicate, Layer7 Live API Creator
merges the global into the resources that are defined for Purchase Order
table.Define Column Access Permissions
You can define the columns that the user role can access by adding a table permission. The
My Orders Write
entity permission specifies the permitted columns for updates, omitting the paid
column, on the Entity Permissions
tab:
For more information about how to define roles for an API user, see Authorization and Role-Based Endpoint Access.
Observations
The Demo API sample illustrates the following:
- You did not write any code for request handling, database access, or business logic. If necessary, you can write code to extend the logic using server-side JavaScript and scale it to complexity (for example, a Bill of Materials explosion with four rules).For more information about how logic scales to complexity, see the Logic Tutorial.
- You solved all the use cases, even though you targeted only Add Order.Layer7 Live API Creatorreuses the logic.For more information about re-use, see Logic.
- The logic is unordered.Layer7 Live API Creatortakes care of the order through logic-dependency analysis.Layer7 Live API Creatorrepeats the analysis on every change, prunes your logic based on actual changes, and SQLs are eliminated/optimized to reduce server traffic. As for ordering, these optimizations are repeated on each change.For more information about howLayer7 Live API Creatordoes not optimize your logic, see Performance.
Advanced Topic: Approaches to Creating Resources
The
Demo
API sample includes examples that demonstrate multi-database resources that are created using various approaches to creating resources and that highlight the advantages of using the declarative approach. These examples reference the Sample
API as the other database resource.The
Sample
API is included with the single-user demonstration package of Layer7 Live API Creator
that is based on Jetty and with the Layer7 Live API Creator
Docker container installation.For more information about the
Sample
API, see the Sample Database.Create Resources using the Declarative Approach
You can extend the declarative approach to creating table-based resources to represent data from multiple databases, joined using a virtual relationship that you define in API Creator. The
CustomerOrders_Declarative
resource demonstrates a multi-database resource between the demo:customer
table and the sample:orders
table in another database. This resource is created using a declarative approach without
any code written.Use this approach when you are connecting to a data source. This approach requires the least effort than the other approaches while providing full services for filtering, pagination, and update from
Layer7 Live API Creator
.The following image shows the
CustomerOrders_Declarative
resource, the CustomerOrders_JS_SubResource
resource, and the CustomerOrders_JS_Totally
resource in the Demo
API sample:
To view the virtual relationship, with the API open, in the Create section, click
Schema
. The Tables tab displays by default. Click the demo:customer
table from the list of tables. View the virtual to-children relationships that are displayed in the Relationships to Children list.For more information about how to access the virtual relationships, see Manage Relationships.
Create Resources using the Combined Approach (Declarative and Code-Based)
The
CustomerOrders_JS_SubResource
resource demonstrates a combination of declarative and code-based approach to creating resources. With this approach, the parent resource is a table-based resource for the demo:customer
table, joined with another sub-resource using the CustomerOrders_JS_SubResource
JavaScript resource. This approach makes a SQL call for customers, and then makes a REST call to the sample:orders
REST endpoint that is connected to a different database using the Sample
API. The combined resource is a compound document resource with approximately 10-12 lines of code that is written in the JavaScript resource. This approach includes minimal services.Use this approach when you need to define code to integrate data from cloud-based data sources.
For more information about how to define resources between databases, see Define Table-Based Resource Types.
Create Resources using the Code-Based Approach
The
CustomerOrders_JS_Totally
resource demonstrates the code-based approach to creating resources. With this approach, you define the code that orchestrates data from different sources (customers from the Demo
API and orders from the Sample
API). This JavaScript resource requires about 50 lines of code. This approach includes minimal services for filtering. It does not provide services for pagination and update. Use this approach when you require the flexibility to integrate an arbitrary source of data.