REST Integration Examples

Integration is a complex subject, covering the following areas:
  • Unified API. Application developers need APIs that hide the complexity of data in multiple locations, without requiring multiple calls that reduce performance.

  • Data Synchronization. Enterprise databases need to share information, with synchronization between systems that store common data.

  • RESTful services. Business logic can be simplified by leveraging existing software, for example, address validation.

  • Existing software. Business logic must leverage the investment in existing software libraries.
The following sections explain how you use Live API Creator to address these subjects.

API Creator Background

Use the following key elements as a background for exploring integration:

API Server as RESTful Server

API Server is built on REST. Your other servers can make RESTful calls to API Server to Get data, and Put/Post/Delete it, all subject to logic and security.

API Creator as RESTful Client: JavaScript Integration

You can invoke other RESTful services, whether for unified API or for update processing to address Data Synchronization and utilization RESTful services using API Server as a natural server.  

Live API Creator provides a rich event model, wherein you can provide server-side JavaScript handlers. You can use these to invoke anything you need, including RESTful services.

Rich Resource Model

Live API Creator is not simply a SQL pass-through. In addition to logic and security enforcement, Live API Creator provides a point-and-click means to define resource endpoints that provide document-oriented (tree) JSON responses.

Taking a pure SQL example:

Definition

Connect your database to API Creator and define the following resource by selecting tables. API Creator automates the joins from the foreign key, which you can override.

Result

This creates a fully executable Resource, which returns a result as shown here.

Observe the Customer data (lines 7-8) includes Orders data (lines 9-18).  Both lists are paginated.

This screen show is taken from built-in RESTLab test facility, but could also use Curl or any other tool.

Unified API

API Creator resources, or endpoints, provide a powerful document-model-based API that is easy to call, with functionality for joining multiple tables, projecting the desired rows and columns, and aliasing names for a clean API.  These services extend beyond relational data, so you can define Resources that combine data from multiple sources, like this:



So, if you are starting with no existing API, you simply connect API Creator and define the Resource above, and you are optional. 

The example illustrates its easy to invoke an existing API.  But what if one does not exist?  No problem - just 
  1. stand up an API Creator REST server for the target database, which provides a RESTful API.   
  2. Create a Resource that returns the desired data, using the join, project and alias functionality described above
  3. Call it as shown in the example above


Data Synchronization

Experience has taught us that large, single corporate databases prove cumbersome to design and iterate.  It is typically better to create databases that address a single function, and share data as required.  

Such sharing might be performed without replicating data between databases, as in the example above.  On the other hand, if the shared data is required to complete transactions, it may be better to synchronize copies it between systems.  There are a number of implications:
  • Business Objects: Synchronization typically involves business objects comprised of multiple rows, such as a customer and their addresses

  • Transformations: Table and column are typically not the same between systems, so a translation layer is required for name mapping

  • Update logic: updates must be trapped and analyzed, to see if they require synchronization.  Such logic should be replicated in each client
Live API Creator makes this really simple.  Let's consider two cases: client (where we send synchronization messages), and server (where such messages are sent).

Synchronization Clients

In this scenario, updates to API Creator data are to be transformed and sent to a remote system.  That is simple to accomplish:
  1. Transformation: Create a Resource that matches the remote system names for objects and attributes.  Note this can be a Business Object - set of related rows.  It's called cust in the screen shot below.

  2. Update Logic: create an event handler (all API Creator updates publish events you can handle in server-side JavaScript), where you can
    1. Use SysUtility.getResource to create a JSON string, per the format of the Resource created in step 1
    2. Send it to the remote system, either by a direct POST, placing it on an Enterprise Service Bus, or using a guaranteed delivery service.




Synchronization Servers

Conversely, your API Creator system can also play the role of server, that is, receiving changes from a remote system.  In the simplest case, you can just
  1. Define a Resource matching the format of the incoming message (again, cust in the example above)

  2. When that Resource is Posted, API Creator will perform the Translation and insert the data - including any associated business rules.
While simple, there is a subtlety we must consider.  While we may want to Post the data the first time, what about subsequent changes from the remote system?  

We could ask the remote system to issue a Put instead.  While that works, it's not really reasonable for them to "remember" which related system has received what data.  

So, API Creator provides an MergeInsert feature, where a Business Object payload can be inserted if it does exist, and updated if it does.  API Creator provides the ability to define your match logic, and runs the business logic associated with the updated data.


REST Service Integration

Data Synchronization is useful, but the advent of RESTful Web Services has ushered in an exciting new era of service that are very useful in applications: address validation, credit checks, etc.  These are extremely useful in business logic.

So, API Creator provides full server-side JavaScript, wherein you can easily invoke such services from events or validation rules.  In either case, Live API Creator provides valuable transaction context such as row and oldRow, so you can invoke such services under the proper conditions (e.g., only when designated values change).

Existing Software Integration

The final piece of the integration puzzle is the library of software assets your organization has been accruing for years. API Creator preserves this investment:
  1. You can upload existing jar files, or JavaScript libraries

  2. From business logic events or rules, you can use server-side JavaScript to invoke these