# Upstream APIs

Typically, FLAT uses one or more upstream APIs where it forwards requests to.

## Validation

You can use Swagger to validate the use of upstream APIs, too!

The [tutorial](/flat/tutorial.md) has a section on [upstream validation](/flat/tutorial.md#upstream-validation).

### Configuration

The configuration takes place in the [`request` action](/flat/reference/actions/request.md) with this [options](/flat/reference/actions/request.md#options):

* `definition` - The path to the swagger definition file (type: `string`)
* `validate-request` - Whether to validate the request (valid values: `true`, `false`, "report-only", default: `false`)
* `validate-request-security` - Whether to validate the request security requirements according to `security` in the swagger definition (valid values: `true`, `false`, "report-only", default: `false`)
* `validate-response` - Whether to validate the response (valid values: `true`, `false`, "report-only", default: `false`)

### Error Handling

`validate-request` checks that the HTTP request that is about to be sent adheres to the upstream API schema. If it doesn't, the request *will not be sent*. The response will be an [error document](/flat/reference/openapi-7/validation.md#system-error-document) with status `400 Bad Request`.

```javascript
{
  "error": {
    "message": "Upstream Request Validation Failed",
    "error": 3202,
    "status": 400,
    "requestID": "W@W8DrjPEMPxyqu4zAL4PAAAABg",
    "info": [
       "Invalid method post."
     ]
  }
}
```

If `validate-request-security` is `true` and the request does not fullfill the security requirements, the request *will not be sent*. The response will be an [error document](/flat/reference/openapi-7/validation.md#system-error-document) with status `401 Unauthorized`.

```javascript
{
  "error": {
    "message": "Upstream Request Security Validation Failed",
    "error": 3207,
    "status": 401,
    "requestID": "W@W8DrjPEMPxyqu4zAL4PAAAABg",
    "info": [
       "Header Security (HeaderAuth): Missing header My-Header"
     ]
  }
}
```

If `validate-response` detects that the response body violates the schema, the response will be replaced by a system error.

```javascript
{
  "error": {
    "message": "Upstream Response Validation Failed",
    "error": 3203,
    "status": 502,
    "requestID": "W@W8DrjPEMPxyqu4zAL4PAAAABg",
    "info": [
       "Type constraint violated in body for error: Object value found, but a string is required.",
       "Upstream status: 404 Not Found"
     ]
  }
}
```

The informational message (array) also contains the original status code of the upstream response – in this case a `404` that may explain the problem.

In both cases, the error will be noted in `$upstream/id/error` where `id` is the content ID of the request (defaults to `main`).

If the request was configured with the [`exit-on-error` option](/flat/reference/actions/request.md#options), errors (e.g. connection errors, invalid requests or responses) cause the normal flow to be aborted. If configured, the [error flow](/flat/reference/openapi-4/routing.md#error-flow) is run. Otherwise a standard error message is substituted as the response to the client request. See [more on error flows](/flat/cookbook/error-flow.md) in the cookbook.

## Mocking

You can mock upstream responses, too. This is handy for writing tests or developing against upstream APIs that do not (yet) exist.

### Configuration

As above, we use [request options](/flat/reference/actions/request.md#options):

* `definition` - The path to the swagger definition file (type: `string`)
* `mock-response` - Whether to mock the response (type: `boolean`, default: `false`)

It works just as [client response mocking](/flat/reference/openapi-3/mocking.md). The mocked response will be used as the HTTP response body for that `request`.

Usually, the `mock` option is set dynamically:

```markup
<flow>
  <request>
  {
      "url": "https://example.com/",
      "options": {
          "definition": "upstream.yaml" {{,}}
          {{if $request/get/mock }}
            "mock-response": true
          {{end}}
      }
  }
  </request>

  <!-- process response -->
</flow>
```

If called with the query param `mock`, the example response of `upstream.yaml` is used:

```bash
$ curl localhost:8080/v1/…?mock
```


---

# 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-6/upstream.md?ask=<question>
```

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.