# Appeler une opération REST

> Ce qui passe, ce qui est retiré, ce qui est refusé, et les en-têtes que la passerelle ajoute à la réponse. Côté produit : Passerelle d'API ; côté exploitation…

Guide - Depuis la version 0.1.0 - Flexway v1.6.3 - https://flexway.io/docs/developer-rest/

> Ce qui passe, ce qui est retiré, ce qui est refusé, et les en-têtes que la passerelle ajoute à la réponse.
>
> Côté produit : [Passerelle d'API](https://flexway.io/docs/product-api-gateway/) ; côté exploitation : [Servir sa première API](https://flexway.io/docs/operations-first-api/).

## La requête

| Élément | Traitement |
| --- | --- |
| En-têtes déclarés par le contrat | Relayés |
| En-têtes du protocole (`Accept*`, `Content-*`, `If-*`, `Range`, `Cache-Control`, `Idempotency-Key`, `traceparent`, `X-Request-Id`, `User-Agent`) | Relayés |
| `Authorization` | Relayé vers une opération sécurisée ; une clé d'API ne l'est jamais |
| Autre en-tête | **Retiré**, sans erreur |
| `Forwarded`, `X-Forwarded-*` | Réécrits par la passerelle ; les vôtres sont ignorés |
| Paramètre de requête non déclaré | `400 malformed_request`, le paramètre nommé |
| Corps ou paramètre hors schéma | `422 invalid_request` ; l'extension `errors` nomme chaque champ |
| Corps trop gros | `413 payload_too_large` |

```json
{
  "type": "https://flexway.dev/problems/invalid_request",
  "title": "The request does not match the contract",
  "status": 422,
  "code": "invalid_request",
  "errors": [ { "field": "body.quantity", "rule": "must be >= 1", "code": "minimum" } ],
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
```

## Corrélation

Envoyez `traceparent` (W3C) pour joindre votre trace à celle de la passerelle, et `X-Request-Id`
pour un identifiant à vous : ils sont relayés à l'API, et un refus les rend dans `trace_id` et
`request_id`. Citez-les dans un ticket - le détail est dans le journal de l'exploitant.

## CORS

Une application de navigateur sur une autre origine doit être **autorisée** par l'exploitant. Une
origine non autorisée reçoit `403` ; la pré-requête `OPTIONS` est traitée par la passerelle. Pour
gRPC-Web, voir [gRPC](https://flexway.io/docs/developer-grpc/).

## Cache

| En-tête de réponse | Sens |
| --- | --- |
| `Flexway-Cache: hit` et `Age` | Servi par le cache de la passerelle, l'API n'a pas été appelée |
| `Flexway-Cache: miss` | Relayé, et proposé au cache |
| `304 Not Modified` | Votre `If-None-Match` correspond à l'`ETag` gardé |

Un succès de cache compte quand même dans votre débit et votre quota. Seules les opérations qui le
déclarent sont cachées ; une réponse authentifiée ne l'est que par tenant **et** par personne.

## Dégradation annoncée

`Flexway-Degraded` dit qu'une réponse est servie en mode dégradé : `circuit-open` (l'amont est coupé),
`upstream-saturated`, `shedding` (sur un `503 overloaded`), `backend-fallback` (inférence servie par un
backend de repli). Ce n'est pas une erreur ; journalisez-le.