USE CASE: APPLICATION INTEGRATION

How to integrate two RESTful APIs

David Brown  |  August 10, 2021

how-to-integrate-two-restful-apis

Integrating applications through RESTful APIs

Integrating a SaaS application typically involves some combination of integrating a RESTful API and/or a webhook.

This use case for this demo is an integration involving two RESTful APIs. The integration consumes the APIs of the Demo Ecommerce API and the Demo Inventory API.

The use case simulates when an order is created in an online store it will be sent to a warehouse for dispatch. In this case, the online store is the Demo Ecommerce API and the warehouse is the Demo Inventory API.

How to download & RUN this REST API to REST API demo

  • If you haven't already done so, get yourself a Martini.
  • Within either Martini Desktop or Martini Online select the "REST API to REST API" demo from the Welcome Screen and click Install:
    screenshot-welcome-screen
  • The Packagedemo003-rest-to-rest will be automatically downloaded. Right-click the Package and click Start. A green icon will indicate it has started:
    screenshot-package
  • Documentation containing a Test Procedure to run the demo is included in the Package readme file \resources\readme\readme.md. The readme file is automatically opened when the Package is started.
    screenshot-documentation
  • The Test Procedure will guide you through the process to place an order, simulate a payment for the order, view the order in the inventory system, dispatch the order, and see the order status update to Shipped.

Line by Line: How this "REST API to REST API" demo works

  • Paying the order from E-Commerce API:
    • When the payment is submitted through this demo’s UI, \\demo003-rest-to-rest\code\demo003\services\PayOrder will be called and start the first phase of the application flow which is creating a dispatch slip once the order was paid successfully.
    • The service \\demo003-rest-to-rest\code\demo003\services\PayOrder uses services generated by consuming the OpenAPI specification of E-Commerce API, Inventory API, and Webhook API.
      • Line 3: demo003.services_imported.ecommerce_api.order.DemoApiEcommerceServiceOrderSelectOrderByReference \ This is a service being used as a Function to pull the order data from E-Commerce API using its reference id.
      • Line 8: demo003.services_imported.ecommerce_api.payment.DemoApiEcommerceServicePaymentInsertPaymentOrder \ This is a service being used as a Function to send payment to the order from E-Commerce API
      • Line 11: demo003.services_imported.webhook_api.WebhookTriggerWebhookEvent \ This is a service being used as a Function to trigger the underlying webhook to create a dispatch slip in the Inventory API upon successful payment.
    • After paying the order, the service demo003.services.webhook_listeners.RequestDispatch will be triggered by the Webhook API. This service uses several services used as a Function to create the dispatch slip in the Inventory API:
      • Line 3: demo003.services_imported.inventory_api.sKU.DemoApiInventoryServiceSkuSelectSKUByProductCode \ This is a service being used as a Function to get the SKU in the Inventory API using the product code.
      • Line 6: demo003.services_imported.inventory_api.dispatchSlips.DemoApiInventoryServiceDispatchslipsPutDispatchSlips \ This is a service being used as a Function to create a pending dispatch in the Inventory API.
    • As a result of the above services being executed, it will mark the order in E-Commerce with accepted status, and once the
  • Updating the order status in E-Commerce API
    • There are two running Martini Scheduler Endpoint running in the background. These endpoints poll at a certain interval checking both the status of the dispatch slip in the Inventory API, and E-Commerce API.
    • The Martini Scheduler Endpoint dispatch-checker polls every 3 seconds, and triggers the service \\demo003.services.scheduler_endpoint.CheckForDispatch. This service calls to services used as a Function to pull the dispatch slips and update the order status in the E-Commerce API
      • Line 3: demo003.services_imported.ecommerce_api.order.DemoApiEcommerceServiceOrderSelectAllOrderByStatus \ This Function pulls all the orders in the E-Commerce API that has an accepted status.
      • Line 7: demo003.services_imported.inventory_api.dispatchSlips.DemoApiInventoryServiceDispatchslipsSelectDispatchSlips \ This Function pulls the dispatch slip record in the Inventory API using the order reference from the order data from E-Commerce API.
      • Line 10: demo003.services_imported.ecommerce_api.order.DemoApiEcommerceServiceOrderUpdateOrderr \ This function updates an order record in the E-Commerce API
    • The Martini Scheduler Endpoint shipped-dispatch-checker polls every 3 seconds, and triggers the service \\demo003.services.scheduler_endpoint.CheckForShippedDispatch. This service calls to services used as a Function to pull dispatch slips with shipped status, and update the order status in the E-Commerce API.
      • Line 3: demo003.services_imported.ecommerce_api.order.DemoApiEcommerceServiceOrderSelectAllOrderByStatus \ This Function pulls all orders in the E-Commerce API that matches the provided order status.
      • Line 7: demo003.services_imported.inventory_api.dispatchSlips.DemoApiInventoryServiceDispatchslipsSelectDispatchSlips \ This Function pulls a dispatch slip that matches the order reference in the Inventory API.
      • Line 10: demo003.services_imported.ecommerce_api.order.DemoApiEcommerceServiceOrderUpdateOrder \ This Function updates an order in the E-Commerce API
    • If demo003.services.scheduler_endpoint.CheckForDispatch is triggered, it will send a request to the E-Commerce API to get all the orders with accepted status.
      • If there are accepted orders, the list of orders will be iterated.
      • During the iteration, for each order with accepted status, it will be checked if the order has a corresponding dispatch slip already created in the Inventory API.
      • If the dispatch slip for the current order in the iteration is found, it will then proceed to update the order in the E-Commerce API with inprocess status.
    • If demo003.services.scheduler_endpoint.CheckForShippedDispatch is triggered, it will send a request to the E-Commerce API to get all the orders with inprocess status.
      • If there are orders that have inprocess status, the list of orders will be iterated.
      • During the iteration, for each order with inprocess status, it will be checked if the dispatch slip associated with the order in the current iteration was already shipped. If the dispatch slip for the current order in the iteration is already shipped, it will then proceed to update the status of the order in E-Commerce as `shipped.
      • If the dispatch slip for the current order in the iteration is not yet shipped, it will ignore it and will proceed to the next order.

Logging order, payment, and dispatch states  to tracker

  • Logging service transactions are added to the services used in this demo by using Tracker functions
  • These logs can be used for auditing what took place during the execution of services being triggered during the application flow.
  • To access the Tracker UI, look for a magnifying glass icon in the menu bar on the top-right corner of the Martini Desktop UI.
  • The Tracker functions are used and placed strategically before or after a certain function is executed
    • Tracker.addDocumentState - This function is used for adding States in a Tracker document.
    • Tracker.addDocument - This function is used to create a new Tracker document. In contrast to Tracker.addDocumentState, this function is the parent document and must exist first before State can be created. Additionally, this function is only used once in the whole application flow for this demo, and it’s added on the entry point of this demo which is the PayOrder service
  • Sample usage:
    • Open the PayOrder service located at \\demo003\services in the code folder of this package.
    • In the PayOrder service, the addDocument function is placed once the service has fetched the order to be paid which is in line 7.
    • Once the payment has been made, and returns a successful response, it will then proceed to trigger the webhook which in turn executes the services in this package that contains the addDocumentState functions that logs the state transitions for the transaction being processed.