Business to Business Example

The Business to Business (B2B) data integration example illustrates a small but non-trivial system, built using Live API Creator. The concepts described are intermediate.

For more information about data integration and key services for data integration, see Data Integration.

Prerequisites:
  • Have the Jetty package for Live API Creator up and running.

  • Have a basic understanding of Live API Creator and have completed the basic training for logic, API creation, and JavaScript extensibility.
    For more information about Live API Creator, see Getting Started.
This document describes:
  • Installation. How to install the B2B example.
  • Readiness Lab. Download and run a series of fun exercises.
  • Test. How to run it.
  • Concepts. This project illustrates many key Live API Creator features. For background information, see the referenced links.
  • Advanced Topics. Extends the basic sample to illustrate advanced Extensibility.

APIs: Modern Application Architecture

The following diagram illustrates typical aspects in the Application Economy: connecting multi-channel transaction sources with logic that governs multiple databases and partner interactions. APIs play a central role in enabling such systems to interact.

In this B2B example, we use Northwind as the central system. This system:
  1. Processes Multi-channel Business. The API server accepts requests from multiple channels: mobile devices, partners, web hooks, web apps, etc. The API definition is not the same as the B2B schema, so requires mapping and transformation logic.

  2. Enforces Credit Limit checks. The business logic to ensure that customer balance <= credit limit is re-used over many User Stories (Place Order, Pay Order, Move Order to new Customer, Change Order Products, Change Order Quantities, etc.).

    1. Issues Partner Alerts. One element of the business logic is notifying the supplier Pavlov when orders include their products, by posting a request in an agreed-upon API format. As in step 1, this API does not match the B2B schema.

  3. Integrates Multiple Databases. Provides an API for a device that shows a Suppler only their promotions, drawn from 2 different databases

  4. Provides UI. Enables Partners to view their information on a tablet, PC, etc.
The following image illustrates a typical B2B system:

Such systems are complex and time-consuming to build, using traditional approaches based on interface documentation (e.g., RAML), frameworks (e.g., Jersey, Jackson, JPA, etc), and IDEs. The example enables you to explore the Live API Creator alternative.

Install the B2B Example

During development, you may often import API definitions using the API Creator. This example uses an install script that automates deployment, just as you might from a source control system. This install script:
  • Creates API projects for B2B and Pavlov (including shared libraries and authentication providers).
  • Performs self-diagnostics, as described in the following sections.

The following installation instructions are for the Jetty version. For more information about the MySQL procedures, see B2B for MySQL.

  1. Download and unpack the b2b.zip
    The zip expands into a typical source control system (scs) directory structure. The src folders contain the API export files (for example, b2b/scs/projects/b2b/src/b2bnwderby.json), shared library code, build scripts, test programs, etc. Click the image at right to enlarge.
  2. cd to your unzipped b2b folder.
  3. You will need various utilities in NodeJS. Install them using the following steps:
    1. Install NodeJS, version 4.x (not 5.x).
    2. Install the Live API Creator npm Packages. For more information, see NodeJS Support.
    3. Verify your Node install (do not proceed if this fails), and is current with a version 2.1.20 or higher:
      lacadmin -V
  4. Run the install script.
  • (On Mac)
Run the following script in Terminal:
sh install.sh derby
  • (On Windows) Issue the following command from a Command window:
install.cmd derby

These install procedures also perform self-diagnostics. The install script invokes a NodeJS program (and optionally, if you have installed it, Python) to post an order, and verify it was successful.

You should see a confirmation screen similar to that shown at right (click to enlarge).

Recap

Explore this Business to Business Example to see all the code/rules used to create the B2B Derby NW API. Let's review some highlights.

The post/verify programs execute the flow shown in the "Modern Architecture" diagram:
  1. An Order is Posted through the resource named PartnerOrder. This provides the mapping and transformation logic to process the order from a partner.
  2. The post activates the business logic. You can compute order totals with product-based discounts, adjust the customer balance, and ensure that the credit limit is not exceeded using about 10 rules. One of these rules (Supplier Alert) alerts our supplier, Pavlov. It's a JavaScript event (about 12 lines) to check what was ordered, and if it's a product supplied by Pavlov, post an alert to the API b2bderbypavlov (representing Pavlov). The resource SupplierAlert is used for mapping and transformation logic.
While this application contains only a few dozen lines of logic and code, it illustrates a great many other patterns common to B2B systems. For example, the SupplierInfo resource integrates multiple databases, and enforces row-level security that enables safe and direct access by partners to view their data. For more information, see b2b/scs/projects/test/node/verifySupplier.js.

At the operational level, the install script illustrates a typical Team Development scenario. The scs folder mimics how you might maintain API Creator objects in a source control system. It includes loadable libraries used for extensibility. The installation scripts provide examples of command line scripting, and API access from Node, Python and PHP programs, or test it in the Rest Lab, as explained in the SupplierInfo resource comments.

The B2B is a key resource in understanding what Live API Creator can do, and how to use it. The following sections walk you through the Concepts Illustrated in the B2B sample.

After exploring, you can work through the Readiness Training. We have selected the exercises that we believe indicate that you're ready to join a project.


Readiness Training

Exploring this page will orient you to most of the key Live API Creator concepts. Follow the links for more details and background.

You can then verify your project-readiness to use Live API Creator using the set of labs built using this API. They are located in the folder unzipped during the previous install process:

b2b/readinessLabs/readinessLabs/Readiness - Live API Creator.docx
A PDF also provided.

Note: You have completed the first lab by installing the B2B Example and testing the API.

Testing

A key strength of the API architecture is that you can call APIs in a variety of ways, across languages and architectures. You can test B2B in the following ways:
  • Rest Lab
  • cURL
  • Command Line
  • NodeJS programs
  • Python
  • PHP
Your API is therefore useful not only for integration, but web apps, scripting, and a host of other applications. Examples of each of the testing methods are provided in your install zip, as explained in the Test B2B.

Using the REST Lab

For new APIs, the simplest approach is to simple use the Rest Lab, since that means you don't have to write any test programs. Follow the previous link to see test JSON you can use.

Concepts Illustrated

The B2B system provides an excellent study in creating an API Back End. It typically follows a process like this:
  1. API Creation - Connect to your database for a default API - point and click customization - nested docs, aliases, etc. This addresses your SQL and Rest handling.

  2. Logic - ensure the integrity of your data with spreadsheet-like reactive logic, extensible with server-side JavaScript

  3. Security - protect data security down to the row and column level by defining table permissions for a role. Integrate authentication with existing corporate security.

  4. Data Explorer - see/update your data with automatically created interfaces providing Filtering, Master/Detail, navigation to related data, etc. Data Explorer is suited for Testing, Prototypes, and Back Office Data Maintenance.

  5. DevOps - see how to save API definitions to a source control system, and build scripts to recreate them
The following sections provide a walk-through of these services.

API Creation and and Customization

The first step is to create your API and customize ("shape") it as required. Swagger documentation is always available. Use it with various tools to generate objects in C#, Java, etc.

Connect to create Default API

The B2B system connects to the database and creates end points for each table, view, and stored procedure. There is no code generation or deploy. The B2B system was created using the install scripts. For more information, see the following sections.

Resources: mapping and transformation

The default API is a good start, but it conforms to your schema. In most cases, you will want to "shape" your API.

For example, API agreements with partners typically do not match internal schema definitions. Custom resources provide key services to map API agreements onto your database and logic:
  • Choose/rename columns, which is a simple approach to mapping and transformation logic. In this image, PartnerOrder.OrderID is aliased to OrderNumber.
  • Specify resource nesting, so B2B requests can include multiple kinds of data, such as the Order and Items.
  • You can use non-persistent attributes (NPA) in resources. For example, in the OrderSummary resource, the SalesRep's fullName is an NPA.
  • You can combine parent subresources into the containing resource. For example, in the OrderSummary resource, the Product information appears with the Order_DetailList properties.
  • Custom resources reuse the logic on the underlying tables.
For more information:

Multi-database Resources

The Resource SupplierInfo joins data from two different data sources. Explore the Data Sources page, and observe the relationship nw:Suppliers -> promos:promotions, based on tables in two different databases. You can test this in the Rest Lab, as explained in the SupplierInfo resource comments.

Resources: leverage with SysUtility

Use SysUtility services to manipulate resources. This is illustrated in the Alert Pavlov event.

Logic

Logic ensures the integrity of your data when update requests are made. For example, we want to 
  1. Verify orders do not exceed customers' credit limits
  2. Provide discounts for healthy orders
  3. Post requests to our supplier Pavlov when orders are received for their products
The following sections illustrate how to perform such multi-table logic, and integration with other systems, via spreadsheet-like reactive logic, extended with server-side JavaScript

Declarative Reactive Rules

Rules are spreadsheet-like expressions (coded in JavaScript) defined on tables and columns. The API server automatically applies them (reacts) to all submitted updates. You don't need to call them. The following executable rules apply to all custom resources. 

Rules can reduce server-side integrity enforcement by over an order of magnitude, with clear and concise user-readable logic instead of tedious code. The requirements are captured as Topics (in the following image, as blue, green, and red boxes), and linked to the logic for traceability.

The following rules ensure that:
  • Check Credit. Rolls up items and orders to verify that the customer's credit limit is not exceeded (if a validation is exceeded, the request results in an exception and the transaction is rolled back)
  • Healthy Food Discount. Provides a discount to customers ordering things like fruits and fish
  • Supplier Alert. When orders are detected for supplier Pavlov, our business agreement requires that we post the order to Pavlov.

For more information:

Extensibility: Table Events

Reactive logic is powerful. To view an example of Bill of Materials solved with a few rules, see the Reactive Logic Tutorial. Extensibility is provided by server-side JavaScript, to ensure there are no limits. For a list of the JavaScript extension points, including their supplied context, see Quick Reference. For more information about extensibility, see Extensibility.

The following image illustrates a commit event, which is an example of such extensibility
.
The code creates a resource instance for the current order and posts it to the supplier Pavlov. This is a table commit event and only active on insert. SysUtility methods are used for data access. The SupplierAlert custom resource translates our schema names into the names agreed upon to be sent to Pavlov ("mapping and translation logic"). req.userProperties is used to maintain state during a transaction.

For more information:

  • About table commit events and row commit logic cycles, see Logic Execution.
  • About the SysUtility JavaScript object and the methods it includes, see SysUtility.
  • About maintaining transaction state, see The Request object.

Extensibility: Loadable Libraries

If you detect patterns in your logic, you can provide re-usable solutions which can be invoked from rules. The following code has a similar effect as the previous event:

if (row.FK_Order_Details_Products.FK_Products_Suppliers.CompanyName == "Pavlova, Ltd." ) {
var response =  postResourceTo("SupplierAlert", 
        { sysfilter: "equal(OrderID:'" + row.OrderID + "')" },          // filter
        req.baseUrl.replace("nw","pavlov") + "v1/SalesReports",   // supplier URL
        { headers: { Authorization: "CALiveAPICreator supplier:1" }});  // supplier auth
    logicContext.logDebug("***Pavlov - POST SupplierReport to Pavlov - " + response ); 
}

You can load logic libraries (such as postResourceTo) as described in the following "Scripted API project deployment" section.

Security

You can secure the data served by your API at the row and column level, and leverage corporate security providers, as described in the following sections.

Custom Authentication Provider

The install zip contains and installs a custom authentication provider called RESTAuthSecurityProvider.js. It authenticates:
  • Admin and demo (to simplify testing).
  • Any user defined in the employees table (first name is login, last name is password. Try Janet Leverling).
  • The user Pavlov. This returns User Data (the ID) used in Role Permission Role Filters.
This configuration is part of the API project export, so occurs when you ran the install script. The auth provider code is located in the zip in the sharedlibs/src directory. The configuration is installed in the script in the sharedlibs/build directory. You can create your own authentication providers for corporate security providers, such as AD and LDAP.

Note: Admin users are used for signing in to Live API Creator. App users are used for signing in to the API Server for data access. Custom authentication providers address app users.

For more information about using a custom authentication provider, see Authentication.

Row Level Security

To ensure that Suppliers see only their own data, the Suppliers role defines a role permission on the Suppliers table. In the following row filter:
"SupplierID" = @{ID}

The ID value is returned in the Custom Auth Provider:
myUserData = {'ID''7'};  //  for multiple globals:  ,{...}

You can verify this in Data Explorer by logging in as Pavlov (any password). One supplier is returned, unlike the result when you login as demo or admin.

Data Explorer: Automatic, Customizable UI

You can customize your UI using Data Explorer Author Mode:
  • The Customer object illustrates the use of Attribute Grouping, and Form Titles (click the thumbnail to the right, to see the full screen). These features are also shown on the Employees screen, which includes images as well.
  • The application illustrates application settings to create a menu of frequently-used tables. For more information about adding and defining the layout for a table, see App Settings.
  • You can explore related data, such as show part information for item within an order, using the Show Parent option.
  • Panel Control provides a feature to Auto Hide the Main Grid Panel when you navigate to related data. Given sufficient screen space, this often reveals a multi-column Display Panel (much more data becomes visible).

Scripted API project deployment

It is a common requirement to script the deployment of an API project, for example to move Source Control System (scs) artifacts into production. The Scripted Creation (previously described) uses techniques described in Import. You can pattern your own deployments by exploring the scripts in the zip.

Custom Endpoints that Return HTML

You can define custom endpoints that are not based on database objects. They can return a variety of response types, such as JSON or HTML. The latter enables you to build and deploy simple menus, without worrying about app deployment. For example, click the following link: localhost http://localhost:8080/http/default/b2bderbynw/B2B.

For more information about custom endpoints that return HTML, see Custom Endpoints.

Code Samples

The sample installs and runs code samples for NodeJS, Python and PHP. You can find these and explore them, under b2b/scs/projects/test.

Advanced Topics

The following extends the example to illustrate JavaScript control over requests:

metadata Tags for Parent Lookup

In our previous example, the partner Posted a request that included the ProductID. This may be reasonable, but sometimes this key is unknown. Instead, it might be required to supply the ProductName.

You can use Services to Insert @metadata action tags to link child rows to parent rows, without the requirement for the client to supply autonum identifiers (which they may not know). See the Lookup function, and observe you can use Request Events to automatically insert @metadata tags.

Related services enable you to designate that request rows can result in either an update of an existing row, or (if not present, the insertion of a new row.

Post the following to PartnerOrder_noID:

 
   "CustomerNumber":"VINET",
   "@metadata":{  
      "action":"INSERT"
   },
   "Items":[  
      {  
         "Quantity":1,
         "Product":{  
            "@metadata":{  
               "action":"LOOKUP",
               "key":"ProductName"
            },
            "ProductName":"Pavlova"
         }
      }
   ]
}


Request Transformation

The requirement in this example is for the Pavlov API to transform the request json received in the Post. This project illustrates a powerful feature, whereby you can use request events to manipulate/transform the request data.

For more information about request events and JavaScript extension points, see Quick Reference.

The code shown in the following image performs such a translation. You can use the logs to view its operation.

The following is the request data submitted:

[  
   {  
      "OrderID":2103,
      "OrderDate":null,
      "@metadata":{  },
      "CompanyName":"Vins et alcools Chevalier",
      "Order_DetailsList":[  
         {  
            "OrderID":2103,
            "ProductID":7,
            "Quantity":2,
            "@metadata":{  },
            "ProductName":"Uncle Bob's Organic Dried Pears",
            "SupplierName":"Grandma Kelly's Homestead"
         },
         {  },
         {  },
         {  },
         {  
            "OrderID":2103,
            "ProductID":16,
            "Quantity":1,
            "@metadata":{  },
            "ProductName":"Pavlova",
            "SupplierName":"Pavlova, Ltd."
         }
      ]
   }


The following is the transformed request, illustrating control over the hierarchy, attribute presence / absence, etc.:

[{"ProductName":"Pavlova",
"CompanyName":"Vins et alcools Chevalier"}]

Subpages (2): B2B for MySQL Test B2B