Adaptor Concept

Adaptors are used to map existing APIs and functionality in a Digital Public Good into a format and scheme that is compatible with the GovStack API specifications.

Adaptors may transform data formats (ie. XML to json), may transform URLs/protocols, or may be used to map GovStack APIs and data structures into sector-specific standards (ie. FHIR patient records).

Key Components and Definitions

Adaptor

An adaptor provides both URL and payload mapping between an existing API developed by a DPG and the GovStack API definitions for the Building Block that the DPG provides functionality for.

Workflow

The workflow Building Block is used to manage more complex transactions where multiple Building Blocks must be called to complete a request (multi-part requests) or where retry/rollback/compensating transactions must be implemented.

Information Mediator

The Information Mediator is used transfer information securely between Building Blocks where communication occurs across the internet.

Key Requirements

1. Adaptors should not be used for outbound requests.

   1. In general it is the application which manages interactions and requests from various Building Blocks

   2. In the event that a Building Block needs to make a direct request from another Building Block, it is recommended to use the Workflow Building Block to manage and URL and data mapping

2. Adaptors should always be tied to specific products. We will not have universal adaptors. Adaptors will be used to transform data based on specific APIs that have been defined by GovStack.

   1. Adaptor technologies may be re-used for different adaptors or we may have a paradigm where a generic adaptor can be configured via config files

3. Adaptors Perform 3 distinct functions (all synchronous):

   1. Class 1 - URL rewriting (mapping a GovStack URL to a URL from a native API)

   2. Class 2 - Payload mapping (transforming data payloads between GovStack and native formats)

   3. Class 3 - Synchronous 1:many calls and composition of responses into a single response

      1. Note: async and/or complex transactions would require the use of the Workflow Building Block

Open

Note: the 4th scenario would not be handled by a GovStack adaptor, but would require the use of a GovStack Workflow Building Block

Potential Adaptor Technologies

An adaptor may be implemented using different technologies. For the purposes of initial sandbox/demo work, it is recommended that Adaptors be built using API Gateway technology, such as that provided by AWS (https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-data-transformations.html )

Should we be able to configure adaptors (ie. use config files) for specific use cases or products?

Other possibilities include:

• API Gateway platforms available from multiple providers

• Tools like Apache Camel or orchestration languages like Ballerina

• Custom code (possibly leveraging config files for different adaptor flavors)

Adaptors and Cloud Instances

While the most common GovStack configuration will be that a Building Block is deployed in the same context as the application that consumes that Building Block, it is possible to use an adaptor to interact with a product (Building Block) that is deployed in a cloud environment.

In this case, the adaptor would mediate the incoming calls and send them to the cloud environment. If the application is a multi-tenant application, the adaptor would need to pass along any headers or payload that are needed to connect to the correct tenant with the correct credentials.

Example Scenarios

Simple Adaptor Example

Adaptors with Information Mediator Example

Adaptor with Workflow Example

Examples of Various Data Mapping Scenarios

GraphQL to REST

This would require a ‘Class 3’ adaptor, where we take the various information that is requested by the GraphQL API and perform a series of REST calls to access the data that is needed. The adaptor would then compose the data from the REST calls into a GraphQL response:

Steps:

1. GraphQL request received by adaptor to look up a patient and return patient information as well as a list of upcoming appointments for that patient

   { query PatientLookup( $name: String, ) { patient( name: $name, ) { id name email appointments { providerName appointmentDate } } }}

2. The Adaptor makes a request to a REST endpoint to get the patient data

3. The Adaptor makes a second request to a different REST endpoint to load the appointments for that patient

4. The Adaptor composes the information from these 2 REST calls and returns a GraphQL response to the calling application

Register Patient Scenario

In this scenario, a remote healthcare worker is using a mobile application that is designed to work with GovStack Building Blocks. The Registration Building Block for this project is an older healthcare clinical system that uses the HL7 version 2.5 standard. The MOH plans to migrate to a newer registration system next year and leveraging the GovStack approach will allow the Registration Building Block to be replaced without rewriting the mobile application.

Steps:

1. The healthcare worker collects information about the patient and submits a request using an API and JSON payload that has been defined by the GovStack Registration spec. This call may look something like:

   1. POST to /api/v1/register

      { name: 'Joe Patient', gender: 'M' DOB: '12/31/2008', address: '111 Main Street', contactMethod: 'SMS', contactDetail: '+47299793921' }

2. The request is received by an adaptor which will map the data to the HL7 format and pass the request to the registration system

   1. POST to /internal/api/register

3. The registration system will return a new Patient ID to the remote healthcare worker application. This response will first be routed to the adaptor

   1. HTTP Response Payload

4. The adaptor will translate this response into the format that the application expects and return it to the initiating application. Note that the adaptor could change the response type, add/remove headers etc.

   1. HTTP Response Payload

Notes/Future Considerations

1. This document does not take into account any process for doing service discovery. This will need to be addressed in the future

2. It is important that adaptors be easy to re-use and reconfigure for new use cases, minimizing development time for each adaptor

3. We need to develop some sort of solution (outside the scope of adaptors) that will wrap an existing database/datastore with REST/API endpoints. Database->Registry with API