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
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.
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.
The Information Mediator is used transfer information securely between Building Blocks where communication occurs across the internet.
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
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.
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:
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
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
name: Jane Doe
providerName: Doctor Anya
providerName: Doctor Anya
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.
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:
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
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
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
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