# Routing An API definition must provide a list of callable *paths* – sometimes also called *routes* or *endpoints*. In `swagger.yaml` this is defined in the `paths` section: ```yaml swagger: "2.0" info: description: "…" version: "1.0.0" title: "My API" basePath: "/v1" paths: /users: get: responses: 200: description: "Get a list of all users" post: responses: 201: description: "User created" /dashboard: get: … ``` One important setting is the `basePath` property. All described API paths are only accessible below that `basePath`. In general, only the paths that are explicitly defined are permissible, i.e. they may not be extended arbitrarily. In our example, the following paths are valid: ``` /v1/users /v1/dashboard ``` While these are undefined (especially those pointing outside of base path): ``` /v1 /users /v1/users/too/long ``` The Swagger docs have more information on [paths and operations](https://swagger.io/docs/specification/2-0/paths-and-operations/). To skirt the rule that every single permissible path must be defined, you can use FLAT's [wildcard path feature](/flat/reference/openapi-2/differences.md#wildcard-paths) to match arbitrarily long request paths. Wildcard paths, i.e. paths ending with `/**`, match all paths sharing the same prefix. For example, by adding the wildcard path `/users/**` to the above definition, the formerly undefined path `/v1/users/too/long` will be matched, too, as well as any other path starting with `/v1/users/`: ```yaml … basePath: "/v1" paths: /users: … /users/**: # Wildcard path matching /v1/users/… /dashboard: … ``` ## Assigning FLAT Flows In FLAT you can assign a [flow](/flat/reference/flow.md) file to every API path to define the request processing. This is done with the `x-flat-flow` property: ```yaml paths: /users: get: # flow for GET /users x-flat-flow: api/users.xml responses: 200: description: "Get a list of all users" post: # flow for POST /users x-flat-flow: api/create-user.xml responses: 201: description: "User created" /dashboard: # flow for /dashboard (all methods) x-flat-flow: api/dashboard.xml get: … ``` You can specify a flow for a path (as in `/dashboard`) or for specific methods/operations (as in `/users`). The same flow can be used for multiple paths or methods. ### Fallback Flow An `x-flat-flow` property set directly in the `paths` object behaves as a *fallback flow*. If the incoming request has matched a defined path, but that path did not define a flow, the fallback flow will be executed: ```yaml paths: x-flat-flow: api/fallback.xml ``` ### Init Flow An *init flow* is a separate flow file that is executed before the regular [flow](/flat/reference/flow.md) or [configured proxy](/flat/reference/openapi-4/routing.md#assigning-flat-proxies) defined for an API path. It is specified by setting `x-flat-init` on the top level in the OpenAPI definition: ```yaml … x-flat-init: init.xml paths: /users: get: … ``` The init flow can be used to [extract common initialization tasks](/flat/cookbook/init-flow.md), e.g. initialize variables or set HTTP response headers. For requests outside of the API `basePath` (e.g. `/` or `/assets`), the init flow is *not* executed. It is only called for API requests. A [`break`](/flat/reference/flow.md#break) statement in the init flow terminates the **whole request**; the regular flow (specified by `x-flat-flow`) is *not* executed. A [`return`](/flat/reference/flow.md#return) statement terminates only the init flow; the regular flow is executed. Terminating [actions](/flat/reference/actions.md) like [`echo`](/flat/reference/actions/echo.md) or [`dump`](/flat/reference/actions/dump.md) will prevent the actual flow from being executed, too. ### Error Flow An *error flow* is an optional separate flow file that is executed if a client request or response validation error has occurred, or if the `exit-on-error` option was set for a [request](/flat/reference/actions/request.md), [proxy-request](/flat/reference/actions/proxy-request.md) or [configured proxy](/flat/reference/openapi-4/routing.md#assigning-flat-proxies) that has failed. It is specified by setting the `flow` property of `x-flat-error` on the top level in the OpenAPI definition: ```yaml … x-flat-error: flow: error.xml … ``` The error flow can be used to [produce error messages with a custom format or status](/flat/cookbook/error-flow.md). Note that the output generated after the error flow has run will not be validated. Additionally, errors encountered while the error flow is processed will not re-start the error flow. ### Default Flow Requests to resources outside the `basePath` are handled by the default flow defined in `conf/flow.xml`. This allows for [serving HTML, images, JavaScript](/flat/cookbook/file-serving.md) and the like. ## Assigning FLAT Proxies If FLAT acts as a proxy for an upstream API on a specific route, you could assign a flow containing a [`proxy-request` action](/flat/reference/actions/proxy-request.md). A simpler way to achieve this is by using `x-flat-proxy` in the `swagger.yaml`: ```yaml basePath: /api paths: /users/**: x-flat-proxy: origin: https://users.upstream.example.com stripEndpoint: true addPrefix: /v4 headers: Correlation-ID: 42 options: timeout: 2 definition: users-upstream.yaml validate-response: report-only ``` A client request to `https://client.example.com/api/users/profile` will be proxied to `https://users.upstream.example.com/v4/profile`. See [wildcard paths](/flat/reference/openapi-2/differences.md#wildcard-paths) for more information about `/**`. `x-flat-proxy` can be used below `paths`, `paths/` and `paths//`. The configuration for `x-flat-proxy` is the same as that for a [`proxy-request` action](/flat/reference/actions/proxy-request.md) (translated from JSON to YAML syntax). If configured, the [init flow](/flat/reference/openapi-4/routing.md#init-flow) is executed before the proxy request. If configured, the [error flow](/flat/reference/openapi-4/routing.md#error-flow) is executed if the `exit-on-error` option was set and the proxy request fails. `x-flat-proxy` and `x-flat-flow` are alternatives and cannot be used in combination. ## Path Parameters Swagger paths can define path parameters: ``` paths: /users/{userid}: x-flat-flow: api/user-info.xml … ``` All named params are available from inside the flow in the pre-defined [variable `$request`](/flat/reference/variables.md#predefined-variables) as properties of the `$request/params` object: ```markup ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://sevenval.gitbook.io/flat/reference/openapi-4/routing.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.