Updating your API Gateway Operations
Building on what we covered in our crash course about setting up the API Gateway, we will now focus on the next critical step: updating your existing API Gateway solution. In this microlearning, we will guide you through the process of updating both the design phase and the create phase of your API Gateway, and explore how these updates impact your solution.
Should you have any questions, please contact academy@emagiz.com.
1. Prerequisites
- Basic knowledge of the eMagiz platform
2. Key concepts
This microlearning centers around updating your API Gateway.
- By updating, we mean: changing existing software to reflect new insights or ideas that have come up during development and testing.
3. Updating your API Gateway Operations
In our crash course on the API Gateway pattern, we have learned about setting up the API Gateway. However, we still need to delve into how to update your existing API Gateway solution. In this microlearning, we will focus on updating the design phase of your API gateway (and the subsequent steps) and the create phase of your API gateway (and subsequent steps). This is to learn the impact of updates and how we can achieve this.
- Updating can happen from Design
- Updating can happen from Create
- Both situations have a different impact
In the remainder of this microlearning, we will discuss both scenarios to clarify their impact.
3.1 Updating from Design
After adding an integration to Create, you can change the error handling, the request and response message structure, the parameters, and more. In all these scenarios, you need to change something in the Design phase of eMagiz. The actual change in these parts of the API Gateway solutions is specified in earlier microlearnings. However, what to do after you have made those changes has yet to be discussed. In this microlearning, we will discuss that process within eMagiz. Note that this process only applies when the operation already exists in Create. If it does not yet exist in Create, eMagiz will create a new entry and exit gate for you based on the configuration in Design.
From our offering on the messaging pattern and how to update it in those scenarios, you can imagine that (parts of) the API Gateway flows need to be updated to reflect your changes. Depending on the exact change, the effect will be seen in the corresponding entry gate or the corresponding exit gate specific to an operation. The division can be made as follows:
- When you change something in the configuration of the API Gateway operation itself (e.g., path, error handling, parameters), the change will only impact the corresponding entry gate.
- When you change something in the configuration of the backend operation (i.e., endpoint, parameter, system request/response), the change will only impact the specific exit gate.
- When you change the gateway request/response message (with transformation), the change will impact both the entry gate and the specific exit gate.
- When you change the API Gateway's security configuration, the infra flow and all entry gates will be updated (by clicking on Update security in the context menu).
eMagiz will automate all changes on the entry gate level except for changing the security configuration due to the impact of such a change. When the change is executed, eMagiz will automatically create a new version of the entry gate to reflect the change. To update changes in the exit gate, you need to execute a manual version bump. This division is made because the exit gate can contain much more customization, while the entry gate is, in most cases, completely generated by eMagiz.
3.2 Updating from Create
Apart from updating your API Gateway solution in Create, you can only update parts of the API Gateway solution in Create. Here, we mainly talk about changing the gateway messages. Any other changes on the 'exit gate' level have no particular impact compared to changing parts of other flows. We discern two parts of updating a (gateway) message that you can execute in the Create phase:
- Changing the dataType (i.e., from dateTime to date)
- Changing / Adding / Deleting valid enum values
In both cases, eMagiz will automatically update your Swagger definition by recreating it to reflect these changes and executing a version bump of the infra flow.
3.3 Updating the Swagger UI
Next to that, you can also update the Swagger UI of your API Gateway solution, so that it better informs your (external) parties to see the specifications of your API Gateway. As you have learned from the previous microlearning of the Swagger UI,
As is the case with all new versions in Create, the changes will only be effective when you deploy your solution via the eMagiz Deploy phase.
4. Key takeaways
- Updates to your API Gateway can be made either during the Design phase or the Create phase, each with distinct impacts.
- Changes made in the Design phase affect the configuration of the entry gate and may necessitate updates to both entry and exit gates, depending on the nature of the changes.
- Changes during the Create phase typically involve modifications to gateway messages, with changes reflected automatically in the Swagger definition and a version bump of the infra flow.
- Adding new operations or updating from either Design or Create does not require a reset of the existing solution.
- Ensure that updates are included in the deployment phase to reflect the latest changes in the Swagger file and runtime infra flow.
5. Suggested Additional Readings
If you are interested in this topic and want more information, please read the help text provided by eMagiz and see the following link: