# Calling an API behind Flexway

> Developer guide: what an application that calls an API served by Flexway sees - credentials, protocols, errors, quotas, retries. It prefigures the developer…

Concept - Since version 0.1.0 - Flexway v1.6.3 - https://flexway.io/en/docs/developer-overview/

> Developer guide: what an application that **calls** an API served by Flexway sees - credentials, protocols, errors, quotas, retries. It prefigures the developer portal (planned for `1.11.0`). Configuring the gateway is in the [operations guide](https://flexway.io/en/docs/operations-overview/).
>
> Product side: [Flexway on one page](https://flexway.io/en/docs/product-overview/); operations side: [Configuring and operating Flexway](https://flexway.io/en/docs/operations-overview/).

## What the gateway does with your request

```mermaid
%%{init: {'theme':'base','themeVariables':{'fontSize':'14px','lineColor':'#94a3b8'}}}%%
graph TB
  APP["Your application"]:::ext
  subgraph FW["Flexway"]
    R["Declared route?"]:::hub
    I["Identity, scopes"]:::hub
    Q["Rate, quota"]:::hub
    V["Contract validation"]:::hub
  end
  UP["Upstream API"]:::spoke
  ERR["RFC 9457 refusal"]:::fail

  APP --> R --> I --> Q --> V --> UP
  R -.->|"404, 405"| ERR
  I -.->|"401, 403"| ERR
  Q -.->|"429, 503"| ERR
  V -.->|"400, 422"| ERR

  classDef hub   fill:#4f46e5,stroke:#3730a3,color:#fff,font-weight:bold
  classDef spoke fill:#0891b2,stroke:#155e75,color:#fff,font-weight:bold
  classDef ext   fill:#64748b,stroke:#334155,color:#fff,font-weight:bold
  classDef fail  fill:#ef4444,stroke:#b91c1c,color:#fff,font-weight:bold
```

| Rule | What it means for you |
| --- | --- |
| **The contract is the truth** | Only the contract's operations (OpenAPI, AsyncAPI, Protobuf) exist. A missing route answers `404`, a missing method `405` with `Allow` |
| **Closed by default** | An undeclared header is **removed** before the upstream; an undeclared query parameter is **refused** (`400`, named); a browser origin not allowed is refused (`403`) |
| **One decision** | REST, gRPC, MCP tool or message: same identity, same quota, same audit |
| **Typed errors** | Always `application/problem+json` (RFC 9457) with a stable `code` - except `/v1/*`, in OpenAI's format ([errors](https://flexway.io/en/docs/developer-errors/)) |
| **Streams not held** | SSE, WebSocket and gRPC streams arrive as the upstream produces them |

## The pages of this guide

| Need | Page |
| --- | --- |
| Get a token, a key or a certificate | [Credentials](https://flexway.io/en/docs/developer-credentials/) |
| Call a REST operation, CORS, caching | [REST](https://flexway.io/en/docs/developer-rest/) |
| gRPC and gRPC-Web | [gRPC](https://flexway.io/en/docs/developer-grpc/) |
| Server-sent events and WebSocket | [Streams](https://flexway.io/en/docs/developer-streams/) |
| Tools for agents | [MCP](https://flexway.io/en/docs/developer-mcp/) |
| Agent-to-agent | [A2A](https://flexway.io/en/docs/developer-a2a/) |
| OpenAI-compatible AI models | [Inference](https://flexway.io/en/docs/developer-inference/) |
| Publish and subscribe to events | [Asynchronous channels](https://flexway.io/en/docs/developer-async/) |
| Receive webhooks | [Signed webhooks](https://flexway.io/en/docs/developer-webhooks/) |
| Kafka producers and consumers | [Kafka clients](https://flexway.io/en/docs/developer-kafka/) |
| Understand a refusal | [Errors](https://flexway.io/en/docs/developer-errors/) |
| `429`, `Retry-After`, throttling | [Rate limits and quotas](https://flexway.io/en/docs/developer-rate-limits/) |
| Retry without duplicating | [Retries and idempotency](https://flexway.io/en/docs/developer-retries/) |
| Deprecation and withdrawal | [Versions](https://flexway.io/en/docs/developer-versioning/) |