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).
Super-concise definition of an adaptor per Taylor Downs:
An adaptor (A) represents a candidate-specific solution to the delta between the API defined in the BB spec (GS) and the actual API (X) of candidate “X”. That’s A = GS - X
.
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
Adaptors should not be used for outbound requests.
In general it is the application which manages interactions and requests from various Building Blocks
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
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.
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
Adaptors Perform 3 distinct functions (all synchronous):
Class 1 - URL rewriting (mapping a GovStack URL to a URL from a native API)
Class 2 - Payload mapping (transforming data payloads between GovStack and native formats)
Class 3 - Synchronous 1:many calls and composition of responses into a single response
Note: async and/or complex transactions would require the use of the Workflow Building Block
These various classes can be illustrated as follows:
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 (Data transformations for REST APIs in API Gateway - Amazon API Gateway )
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:
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
{
id: 12345
name: Jane Doe
email: jane@example.com
appointments: [{
providerName: Doctor Anya
appointmentDate: 10/01/2023
}, {
providerName: Doctor Anya
appointmentDate: 10/07/2023
}
]
}
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:
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:
POST to /api/v1/register
{ name: 'Joe Patient', gender: 'M' DOB: '12/31/2008', address: '111 Main Street', contactMethod: 'SMS', contactDetail: '+47299793921' }
The request is received by an adaptor which will map the data to the HL7 format and pass the request to the registration system
POST to /internal/api/register
PID[BAR]1[BAR]MRN[BAR][BAR]PCN[BAR][BAR][BAR]Joe Patient[BAR]M[BAR][BAR]31/12/2008[BAR][BAR][BAR]111 Main Street[BAR][BAR][BAR][BAR][BAR]+47299793921
The registration system will return a new Patient ID to the remote healthcare worker application. This response will first be routed to the adaptor
HTTP Response Payload
PID[BAR]1[BAR]MRN[BAR][BAR]PCN[BAR]8789247
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.
HTTP Response Payload
{ patientID: 8789247 }
Notes/Future Considerations
This document does not take into account any process for doing service discovery. This will need to be addressed in the future
It is important that adaptors be easy to re-use and reconfigure for new use cases, minimizing development time for each adaptor
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