Context
At Deloitte Platform Engineering (DPE), we hold a substantial digital footprint within the Platform Engineering and Systems Integration national practice, offering professional services to meet clients' needs. Our strength comes from an expansive portfolio in providing innovative consulting services to cloud platforms and systems integration, to achieve client strategy. The acquisition of the Microsoft Azure specialist company, Mexia, bolstered this capability, moving us to the forefront as experts in providing Azure platform services. In addition, Deloitte Consulting is a Global Elite Partner with Dell Boomi, one of the leading iPaaS (Integration Platform as a Service) solution providers that enable fast paced application integration across hybrid IT landscapes.
This article presents an outcome of a recent successful collaboration between our Azure Engineers and Dell Boomi Integration Specialists, which delivered a framework adhering to Contract-First API Development philosophy. We will show how this has been achieved with Boomi in conjunction with Azure API Management (APIM), Azure DevOps and SwaggerHub.
Boomi and Azure API Management
We observe that most of our Boomi-based clientele have chosen Boomi as their core enterprise integration platform for its low-code, rapid development capability and its hybrid deployment model.
Often, we have seen this capability must be supplemented by a fully-fledged API Management product (e.g. Azure API Management) especially for an API-led Digital Transformation project. The Boomi API component can implement REST APIs with the API definition published on Azure API Management. The backend is configured to point to the Boomi runtimes running on local Boomi runtimes (Atoms or Molecules) hosted on Azure VMs and On-Premise (private data centre) with Azure Express Routes.
Boomi has adopted Swagger 2.0 as its standard for REST API development. Boomi API Contract design requires Swagger specification files (YAML or JSON format) to be authored externally using an external tools such as Swagger Editor.
Using Boomi's API Component, Boomi offers the ability to import a Swagger 2.0 API in a wizard-driven approach. Upon import Boomi will scaffold the various resources and endpoints to be refined later.
In addition, Azure API Management supports the auto-creation of mock services to support rapid consumption and testing of the API definitions. Mocks are driven by the example responses provided in the Swagger specification. Once the APIs are ready for consumption, they can be published on the Azure Developer portal, an automatic and customisable API documentation tool. API consumers can then discover the APIs, request access, read the documentation and try out the APIs.
Full-lifecycle API Design
Well-designed APIs are at the heart of how successfully your API-led digital transformation is adopted and used by the consumers. Allowing user to easily understand API resources allows easy API utilisation. In order to realise these benefits, the process by which a business capability gets transformed into a consumable service has to be correctly identified and practiced. A Contract-First approach API development can help achieve this ensuring that API definitions (and implementations) are version controlled.
API Developer Workflow
Once created, appropriate measures must be implemented to track API specification changes that would affect the implementation, and in turn, consumers. Consequently, the API lifecycle should include support for versioning.
Considering these requirements, our Engineers created a developer workflow to incorporate the integration between different tools with a focus of automation. In this solution, the Boomi Atoms are hosted within Azure VMs and the APIs are published and managed in the Azure cloud using Microsoft Azure APIM.
The following diagram (click image to enlarge) illustrates the API developer workflow:
- Contract definition
- SwaggerHub Integration with Azure APIM and Azure DevOps
- Configure API in Azure APIM
- ARM template creation
- CI/CD Process
Contract Definition
Once the interface design has been agreed, it is persisted to the API portal as a Contract which multiple teams can develop from. The Swagger Editor is a powerful tool that we have repeatedly utilised to define API contracts. The API contract is then exported from SwaggerHub to the API management platform; in our case, Azure APIM. It is worth noting that SwaggerHub gives the options to download resolved or unresolved API definitions. If the API definition contains $ref links to external files or domains, the user can either download it with the contents of the external files in the resulting definition (resolved definition) or without them (unresolved definition).
Integration of SwaggerHub with Azure Resources
SwaggerHub has the ability to integrate with Azure APIM, allowing the export of API definitions into Azure. This enables API Designers/Developers to create and modify APIs in SwaggerHub and deploy them to Azure APIM. To create a new integration, several parameters are required:
- Azure APIM service instance name
- Azure API identifier
- Management API Access Token.
Once these have been established and the integration is executed, the API will be synced with the configured Azure APIM instance. In addition, Azure DevOps Services integration allows the API definitions to remain synced with source control. Each time the API is updated in SwaggerHub, this integration will update the code in the given repository. Once deployed to the Development environment, Azure DevOps can be used to propagate the APIs to higher controlled environments.
API Configuration
There are certain configurations pertaining to Azure APIM that cannot be made using SwaggerHub, such as Named Values, API Products, and Policy -level changes. Once the API has been synced with the APIM instance, these API changes can be made where necessary by the API developers by accessing the API via the Azure Portal.
ARM Template Creation
The ARM templates can be generated by using this custom utility, to extract existing configurations of the APIs in an API Management instance. These APIs are then deployed to different environments using Azure Build and Release Pipelines.
CI/CD Process
Each API resides in its own Azure DevOps repository which contains its ARM template and related policy definitions. Similarly, each API has its own Build and Release pipeline. This way, it can be promoted to different environments independently through the Release Pipeline.
Summary
Our approach to developing RESTful APIs using a Contract-First approach ensures that feedback from the API consumers is captured early on in the software cycle. The API contract definition is produced in the initial design stage and the use of an agile and an interactive delivery process ensures that challenges faced by traditional waterfall design are eliminated. Using contract definitions reduces the likelihood of friction amongst teams later on.
A key benefit of this approach is the engagement of API consumers. Early engagement of stakeholders reduces feedback loops. API mocking also allows quick testing and integration of APIs by application developers. This allows responsive feedback and incorporation early on in the lifecycle. At the end of the process, the API has been thoroughly tested an refined.
In this article, we highlighted the importance of following a Contract-First approach when it comes to developing REST APIs in Boomi. We also presented an approach that enables full lifecycle management for the API design process in Boomi and exposing them via Azure API Management.
In a past article, we have already addressed the automation of Boomi application deployment using Azure DevOps, resulting in a powerful CI/CD framework for the ongoing development of Dell Boomi integrations on Azure.
In summary, Deloitte Platform Engineering have successfully architected robust production solutions. This is possible through our strong engineering prowess and the deep understanding we possess at DPE on the requirements vs the capabilities of various tools to deliver an innovative solution.