Bibliothèque de référence

Exprimer clairement chaque intention API.

Des exemples OpenAPI 3.1 prêts à adapter, avec une frontière explicite entre le contrat public, les extensions portables et la configuration d’exposition.

01 · Routage

Les routes sont natives dans OpenAPI.

Utilisez `paths`, les méthodes HTTP, les paramètres et `operationId`. Une extension `x-route` dupliquerait le standard et rendrait les outils moins interopérables.

Dans l’OASChemin public, méthode, paramètres, réponses et URL exposée.

openapi.yaml

openapi: 3.1.0
info:
  title: Payments API
  version: 1.2.0
servers:
  - url: https://api.example.com/payments/v1
paths:
  /transactions/{transactionId}:
    get:
      operationId: getTransaction
      tags: [Transactions]
      parameters:
        - name: transactionId
          in: path
          required: true
          schema: { type: string }
      responses:
        "200": { description: Transaction trouvée }
        "404": { description: Transaction inconnue }

02 · Upstream

L’upstream ne doit pas être figé dans l’OAS.

`servers` représente l’adresse publique vue par le consommateur. L’adresse réelle du service varie selon l’environnement et reste dans un document d’exposition compagnon.

Hors de l’OASDNS interne, port, egress, certificats, health check et délais réseau.

exposure.yaml

apiRef: payments@1.2.0
targets:
  - environment: production
    region: eu-west
    upstreamRef: payments-prod-eu

upstreams:
  payments-prod-eu:
    url: https://payments.internal.example:8443
    protocol: https
    tls:
      verify: true
      caRef: secret:pki/internal-ca
      clientCertRef: secret:pki/payments-client
      sniHost: payments.internal.example
    health:
      path: /health
      expectedStatus: 200
    timeouts:
      connect: 5s
      read: 30s
      write: 30s

03 · Authentification

Une intention portable, jamais un plugin.

L’extension décrit le résultat attendu. Les secrets sont référencés, jamais inclus dans le document.

`type` est obligatoire, y compris pour une API publique avec `none`.
Les audiences et scopes sont des exigences fonctionnelles.
Aucun mot de passe, token ou certificat en clair.

x-api-policies · auth

x-api-policies:
  auth:
    type: oauth2
    oauth2:
      introspectionRef: secret:oauth/introspection
      requiredScopes:
        - payments.read

# Variante JWT
x-api-policies:
  auth:
    type: jwt
    jwt:
      issuers: [https://identity.example/realms/apis]
      audiences: [payments]
      jwksRef: secret:pki/identity-jwks

04 · Maîtrise du trafic

Définir la sémantique observable.

La limite, la fenêtre et la clé de comptage appartiennent au contrat. Les paramètres de connexion à l’upstream restent dans l’exposition.

Cohérence`per-consumer` exige une authentification permettant d’identifier le consommateur.

x-api-policies · traffic

x-api-policies:
  rate-limit:
    limit: 100
    window: 1m
    scope: per-consumer
    algorithm: sliding-window
    onExceeded: reject
  timeouts:
    request: 30s
  request-size-limit:
    maxBodySize: 10MB

05 · Protection

Composer des garde-fous cohérents.

Les règles communes vivent à la racine. Une opération peut les préciser sans recopier tout le contrat.

HéritageL’opération gagne pour la clé redéfinie; les autres règles racine continuent de s’appliquer.

x-api-policies · protection

x-api-policies:
  cors:
    allowOrigins: [https://app.example.com]
    allowMethods: [GET, POST, OPTIONS]
    allowHeaders: [Authorization, Content-Type]
    allowCredentials: true
    maxAge: 1h
  ip-restriction:
    allow: [10.0.0.0/8]
    deny: [10.6.6.0/24]
  request-validation:
    validateBody: true
    validateParams: true
    onInvalid: reject

paths:
  /health:
    get:
      x-api-policies:
        auth: { type: none }

06 · Matérialisation

Une même intention, deux résultats.

Ces ressources sont générées à partir de l’OAS et du document d’exposition. Elles illustrent la traduction; elles ne doivent jamais être recopiées dans le contrat OpenAPI.

Kong EnterpriseHTTPRoute + KongPlugin

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: payments
spec:
  rules:
    - matches:
        - path: { type: PathPrefix, value: /payments }
      filters:
        - type: ExtensionRef
          extensionRef:
            group: configuration.konghq.com
            kind: KongPlugin
            name: payments-rate-limit
      backendRefs:
        - { name: payments, port: 8080 }
---
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata: { name: payments-rate-limit }
plugin: rate-limiting-advanced
config:
  limit: [100]
  window_size: [60]
  window_type: sliding
  namespace: payments

Gloo GatewayHTTPRoute + TrafficPolicy

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: payments
spec:
  rules:
    - name: payments
      matches:
        - path: { type: PathPrefix, value: /payments }
      backendRefs:
        - { name: payments, port: 8080 }
---
apiVersion: gateway.kgateway.dev/v1alpha1
kind: TrafficPolicy
metadata: { name: payments-rate-limit }
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: payments
      sectionName: payments
  rateLimit:
    local:
      tokenBucket:
        maxTokens: 100
        tokensPerFill: 100
        fillInterval: 60s

API de Gloo GatewayLe produit est Gloo Gateway. Ses ressources récentes conservent le groupe Kubernetes gateway.kgateway.dev; ce nom technique ne désigne pas ici un troisième produit.

Fidélité de traductionKong Enterprise matérialise la fenêtre glissante avec rate-limiting-advanced. Une cible ne sachant pas préserver l’algorithme demandé doit refuser la génération. Pour une fenêtre fixe, Kong OSS peut produire le plugin rate-limiting.

Upstream externeKong matérialise une destination externe selon son modèle de service; Gloo Gateway génère un Backend référencé par HTTPRoute. Dans les deux cas, l’adresse provient du document d’exposition, pas de servers.

07 · Vue complète

Le contrat minimal d’un produit API.

Une base cohérente associant identité, routage, modèles, sécurité et réponses standard.

Télécharger le YAML