# Flow

The flow describes how the incoming request from the client is transformed into the outgoing response. The flow comprises [*actions*](https://sevenval.gitbook.io/flat/reference/actions), [control structures](#control-structures) and [variables](https://sevenval.gitbook.io/flat/reference/variables).

Each endpoint of your API can have its individual flow specified by `x-flat-flow`, see [Routing](https://sevenval.gitbook.io/flat/reference/openapi-4/routing).

Here we have a flow with [`if-elseif-else` conditional statements](#if-elseif-else) and some [`echo` actions](https://sevenval.gitbook.io/flat/reference/actions/echo) evaluating the [`$request` variable](https://sevenval.gitbook.io/flat/reference/variables):

```markup
<flow>
  <if test="$request/query = 42">
    <echo>Yeah, that's it!</echo>
  </if>
  <elseif test="$request/query">
    <echo>Um, no!</echo>
  </elseif>
  <else>
    <echo>Do you know the answer?</echo>
  </else>
</flow>
```

## Control Structures

### `break`

`break` stops the flow processing for the current request. It may be used in [sub flows](https://sevenval.gitbook.io/flat/reference/actions/sub-flow) or the [init flow](https://sevenval.gitbook.io/flat/openapi-4/routing#init-flow), too.

Response processing (such as validation and sending out the response) will continue, though.

A `break` statement should usually be executed conditionally, because otherwise none of the following statements will ever be executed.

```markup
<flow>
  <break/>
  <echo>will never be reached</echo>
</flow>
```

See also:

* [`echo`](https://sevenval.gitbook.io/flat/reference/actions/echo)
* [`dump`](https://sevenval.gitbook.io/flat/reference/actions/dump)
* [`return`](#return)
* [`sub-flow`](https://sevenval.gitbook.io/flat/reference/actions/sub-flow)

### `if`-`elseif`-`else`

The `if` statement and the optional `elseif` and `else` statements allow for conditional execution of flow blocks.

```markup
<flow>
  <if test="…">…</if>

  <if test="…">…</if>
  <else>…</else>

  <if test="…">…</if>
  <elseif test="…">…</elseif>

  <if test="…">…</if>
  <elseif test="…">…</elseif>
  <elseif test="…">…</elseif>
  <else>…</else>
</flow>
```

Conditional expressions are defined in the `test="…"` attributes of the `if` and `elseif` statements. If such an expression evaluates to `true`, the flow block inside that `if` (or `elseif`) will be executed. All directly following `elseif` and `else` blocks will then be skipped.

If the result of that expression is `false`, the block will be skipped and the condition of the following `elseif` statement will be checked, if applicable.

The block associated with the first matching conditional expression will be executed – or if all expressions were evaluated to `false`, the `else` block will be executed.

### `if` attribute

The `if` attribute allows for conditional execution of a single action:

```markup
<flow>
  …
  <error if="$upstream/my_request/status != 200">
  {
    …
  }
  </error>
  …
</flow>
```

### `return`

`return` quits the current [sub flow](https://sevenval.gitbook.io/flat/reference/actions/sub-flow) and returns to its parent flow. If `return` is used in the [init flow](https://sevenval.gitbook.io/flat/openapi-4/routing#init-flow) the regular API path flow will still be executed. A `return` statement on the top-most flow behaves like [`break`](#break).