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);

  • retrieve specific info (to identify the origin of the request, for example);

  • 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:

flow all interceptor

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

Configuring API flows

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

  1. The scope of execution, containing:

    • Resources: it displays all API features. When All is selected, the flow will be applied for all the resources. flow resource interceptor

    • 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. flow operation interceptor

  2. The set of interceptors, spanning these categories: Traffic, Security, Mediation, Tracing, Transformation, Custom.

  3. 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.

  4. 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.

  5. 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 icon backend button, through which you can also define the certificate to be used and a specific timeout.

As of now the gateway utilizes connection reuse by default. Check our FAQ on how to manage gateway’s connection reuse.

  • 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.

      Find out more about how timeout works on this page of our FAQs.
flow destination

API Destination

Path Params

If the name of a parameter is repeated, the gateway will repeat the value, but it will disregard the name of the parameter that is in the resource, only considering the order of parameters received.

Examples:

Considering the resource GET /path/{param1}/path/{param2}/path/{param3}, with the following request sent /path/1/path/2/path/3:

  1. if the destination is GET /path/{param1}/path/{param2}/path/{param3}, the gateway will forward to /path/1/path/2/path/3

  2. if the destination is GET /path/{param3}/path/{param2}/path/{param1}, the gateway will forward to /path/1/path/2/path/3

  3. if the destination is GET /path/{param1}/path/{param2}/path/{param1}, the gateway will forward to /path/1/path/2/path/1

  4. if the destination is GET /path/{param3}/path/{param2}/path/{param3}, the gateway will forward to /path/1/path/2/path/1.

Headers

The Transfer-Encoding header is removed from the moment the request travels through the gateway, both in response and in request. For more information, read our documentation about removing headers.

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 parent child

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.

interceptors natural order

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.

flow break

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

flow break restore

Warning and frequent questions about flows

  • Sometimes you try to find an interceptor to add into the flow and it seems to be missing. Try checking whether that interceptor can be used for the scope you’ve selected (API as a whole, resource or operation level).

  • There are interceptors that can be added to both the request and response flows, but there are some which can only be added to one of them. You can consult the specific documentation of the interceptor you want to configure for more information.

  • The order of interceptors in the flow is the order they will start to run in the call. Keep that in mind when you drag interceptors into the flow. Once a call is complete, you can check the execution order in the Trace details. Go to General Trace > desired call > GATEWAY TRACE tab.

  • When you edit an API’s flow, don’t just save your changes on the flow’s editing screen. When you are redirected to the API’s overview page, save the API itself.

  • You can only identify the app that originated a call if you add an interceptor that validates client ID into the flow (OAuth or Client ID Validation). Also, the app must be associated with the API via a plan.

More frequent questions regarding API flows on our FAQs section.
Thanks for your feedback!
EDIT

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