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:
MySQLWorkbenchScreenSnapz001.png  
Solution
The sample solution uses a familiar problem–customer, PurchaseOrder, and LineItems–to introduce various concepts in 
Layer7 Live API Creator
:
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:
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:
  DemoAPI_Resources.png  
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:
  • About pagination, see GET.
  • About optimistic locking and changing summary information, see PUT.
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:
  Screen Shot 2018-05-17 at 3.06.46 PM.png  
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:
Screen Shot 2018-05-17 at 3.08.28 PM.png
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 Creator
     reuses the logic.
    For more information about re-use, see Logic.
  • The logic is unordered. 
    Layer7 Live API Creator
     takes care of the order through logic-dependency analysis. 
    Layer7 Live API Creator
     repeats 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 how 
    Layer7 Live API Creator
     does 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:
  DemoAPI_CustOrdersDeclarative.png  
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.