Designing your API Gateway
In this microlearning, you will learn how HTTP operations are defined in eMagiz, how these operations relate to your backend integrations, and how to determine the message structures used by your API Gateway. By the end, you will understand how to configure API operations and manage the data models that support them.
If you have any questions along the way, feel free to reach out to us at academy@emagiz.com.
1. Prerequisites
- Basic knowledge of the eMagiz platform
- Basic knowledge about API Gateways
2. Key concepts
- API Gateway: A collection of REST API operations that can be exposed externally to provide controlled access to applications and business processes.
- HTTP Operation: The combination of an action (i.e. Create, Read, Update or Delete) and the resource (i.e. Client, Order, Employee) it should be performed on.
3. HTTP Operations
In eMagiz, HTTP operations define the interactions that are available for the resources exposed through your API Gateway.
An HTTP operation consists of an HTTP method and your HTTP resource. The HTTP method defines the action that can be performed on the HTTP resource. In eMagiz terms, these resources are represented by the message types you defined in Capture. The available methods are based on standard REST principles.
The most common HTTP methods are:
- POST: Creates a new resource.
- GET: Retrieves a resource.
- DELETE: Removes a resource.
In addition, the eMagiz API Gateway supports:
- PUT: Replaces an existing resource with an updated version.
- PATCH: Updates only the specified field(s) in an existing resource.
- HEAD: Retrieves technical details about a resource without returning the resource data itself (used to check if a resource exists).
HTTP methods can make use of a request body that contains the data you want to send to the API. In eMagiz this is your request message.
- POST typically includes a body containing the data for the new resource.
- PUT typically includes a body containing the complete updated version of a resource.
- PATCH typically includes a body containing only the fields that need to be updated.
- GET, DELETE, and HEAD typically do not include a body at all. The resource is identified through the resource path in the URL.
Similarly, HTTP methods can send back a response body or send only a status code and relevant headers. The status code tells you if your request has been successful or not. The response body in eMagiz is your response message.
- GET usually returns a response message containing the requested resource.
- POST, PUT and PATCH often return a response message containing the created/updated resource but this is not required
- DELETE sometimes returns a response containing a confirmation or the deleted resource, but typically only returns a status code.
- HEAD never returns a response body, all relevant information is sent via the headers.
This is relevant for determining if you need to include a message structure for your operation, and if this needs to be for a request or a response message.
3.1 Determining the HTTP Operations in eMagiz
When you go to the Design phase in eMagiz, you initially see the integrations that you have drawn in Capture.
The green lines depict the actual integrations towards the back-end systems. The blue lines indicate which resources an external system can potentially access via the API Gateway. The number next to the message type indicates how many operations are defined for that resource. By default, eMagiz automatically creates a GET operation for every message type.
To add additional operations, start at the back-end integration. When you expand this integration, you will see the operations that are currently available for the message type. By right clicking an existing operation, you can edit it or add a new operation using the Edit or Add integration option.
You can then configure your operation as seen below. A simple resource path is auto generated by eMagiz, which can be extended with parameters later on.
3.2 Passthrough vs. transformation
When configuring an operation, you must choose between a passthrough or transformation integration. This is a key decision for how eMagiz creates your integration in the Create phase.
In the passthrough scenario, you re-use the message definitions and operations from your back-end in the front-end of your API Gateway. Requests that users of your API Gateway execute are passed through unchanged to the back-end APIs. This is naturally only possible if your back-end APIs use the REST protocol and adhere to its principles.
When selecting the passthrough option, the pop-up provides a selection field where you choose to which back-end operation this integration is connected. The back-end operation has to be configured in the back-end system. More on that in the following microlearning: Configure A Backend Operation
If your backend is not compatible, you must choose Transformation here so you can create custom flows in the Create phase that fit the needs of your exposed backend systems.
4. Message structures
Now that we have covered managing which operations your API Gateway exposes, we can look at the content of the messages that are flowing through your API Gateway.
4.1 Gateway data model
To determine the message structure that should be used in the front-end of your API Gateway, eMagiz provides the Gateway data model. This data model can be based on standards (i.e. OTM5), can be custom made, or a combination of both.
To manage your Gateway data model, you navigate to Design and open the context menu on the API block in the center of your Design Overview.
When editing the Gateway data model, you can add entities and attributes and the API data model has full version control, including a history log where you can trace all changes done to it.
4.2 System messages
System messages are used for your backend systems. They show the message structure that your backend systems expect. You can edit the message structures in the same way as the Gateway data model. However, there is no version control or history log here.
eMagiz provides the option to import an Open API specification that determines the structure of your system messages. In that case, you do not have to manually create the message structures.
5. Key takeaways
- HTTP operations in eMagiz are defined by combining an HTTP method (GET, POST, PUT, PATCH, DELETE, or HEAD) with a resource represented by a message type.
- When configuring operations, you must decide between a passthrough integration (reusing backend APIs) or a transformation integration (creating custom flows).
- Message structures are managed through the Gateway data model for the API Gateway and system messages for backend systems, with support for OpenAPI imports.
6. Suggested Additional Readings
If you are interested in this topic and want more information on it please read the help text provided by eMagiz and read the following links: