Flows

What are API flows?

The architecture for APIs exposure that is most widely adopted on the market advises the separation of responsibilities, which renders the presence of an API gateway as an intermediary element between clients and the backend paramount.

By default, all data in a request are transferred to the backend through the gateway routing without any modifications. The same goes for the response sent by the backend. By default, all response data are sent unchanged to the client that originated the request.

Nevertheless, there are several situations where you need to modify the request data before sending it to the backend, or change the default response that will be returned to the client. For example, you might want to:

add information to the request before forwarding it to the backend (message enrichment);
remove or mask sensitive information that should not be stored in logs;
make routing decisions based on message content;
compose more than one call to internal services in the same external request.

The definition of an API includes the configuration of incoming and outgoing flows of messages. Along these flows, interceptors can be added at specific points, and they will be executed in a well-defined order. They are the elements that apply logic and establish behaviour.

The execution of the interceptors follows a tree hierarchy, respecting the order in which they were configured.

The image below shows a scenario in which interceptors are added to the incoming and outgoing flows of messages:

You can add default interceptors (ready for use on your Manager) or custom interceptors to your API flows. Access here to read about the available interceptors.

Configuring API flows

In the configuration of the flow, the following things can be defined:

The scope of execution, containing:
- Resources: it displays all API features. When All is selected, the flow will be applied for all the resources.
- Operations: it displays all operations for the selected resource. Again, if All is selected, the flow will be applied to all operations belonging to the resource.
The set of interceptors, spanning these categories: Traffic, Security, Mediation, Tracing, Transformation, Custom.
The execution point of the request made from the client to the server. The order of the interceptors — from left to right — defines what the processing will be like. All interceptors are valid for this execution point.
The execution point of the response returned from the server to the client, through some processing by the interceptors. The order of the interceptors is from right to left. Some interceptors are not part of this execution point, such as Client ID Validation, Access Token Validation and OAuth.
The destination of the API, which can be defined as the same for all calls to the API or specific for a given resource or operation (depending on whether you chose All in the Resource and/or Operation fields). To set up the destination, click the button, through which you can also define the certificate to be used and a specific timeout.
- The timeout determines the waiting time for the consumption of a given resource or operation. When the time of a request exceeds the timeout value configured, the request is aborted and an exception is launched by the system with status 502.
  - The timeout field can be defined directly, with a value in seconds, or with an environment variable.
  - The timeout present in the destinations has an execution hierarchy: it runs from the most general level to the most specific one. E.g.: A timeout defined for "All" will be applied to all features and operations, unless a different timeout is defined in a more specific component.

Inheritance of flows

We can create multiple flows for one API call.

The flows follow a hierarchy model, that is, the parent’s interceptors will be inherited by its children, but changes to children’s flows will not be reflected in the parent.

Logos of interceptors inherited from a parent will be dark grey, whereas new interceptors will be in colour.

Flow breaks

A flow break is characterised by a change in the order of interceptors inherited from a parent flow. In this case, all changes made to the parent flow are not passed on to the children.

What causes flow breaks:

changing the order of interceptors from a parent;
changing the order of a child’s interceptors, before the interceptors inherited from a parent;
changing the order of a child’s interceptors, amidst the interceptors inherited from a parent;
adding a new interceptor before the interceptors inherited from a parent;
adding a new interceptor amidst the interceptors inherited from a parent.

What DOESN’T cause flow breaks:

changing the order of the child’s interceptors after the parent’s interceptors;
adding a new interceptor after the interceptors inherited from a parent;
changing the values of the parent’s interceptors.

If you change values in the child’s interceptors, these changes will be transmitted to the child’s offspring. However, if there is a change in the value of a parent, it will not be passed on to the children or to the children’s offspring.

The image below represents a normal child flow, in which the grey interceptors are inherited from a parent and a Log interceptor is added to the request, obeying the order of interceptors.

And you can see an example of a flow break below. The order of the interceptors has been changed: a Client ID Validation interceptor has been added before the first interceptor inherited from the parent flow (Rate Limit). Thus, any changes made to the parent flow will not be applied to the flow at hand.

You can reverse the flow break by clicking the Restore button, located next to the Operations selection field.

Thanks for your feedback!

EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]