Aller au contenu principal

Protocoles

Les systèmes réels ne sont pas uniquement REST. Powerduck modélise sept protocoles dans des entrées de chemin OpenAPI ordinaires via l'extension x-protocol. Les opérations de streaming et RPC vivent dans la même spécification que REST, sans outil séparé ni conversion forcée en REST.

Chaque opération non HTTP reste une entrée de chemin ordinaire avec méthode HTTP et responses."200".description.

  • graphql, grpc, mcp, a2a utilisent post.
  • sse, websocket utilisent généralement get.
  • http est la valeur par défaut et x-protocol est omis.

SSE​

Les Server-Sent Events sur HTTP utilisent x-protocol: "sse". Le type de média de flux est text/event-stream, et le payload d'un événement unique se décrit avec itemSchema, pas schema.

paths:
  /events:
    get:
      x-protocol: sse
      responses:
        "200":
          description: Event stream
          content:
            text/event-stream:
              itemSchema:
                type: object
                properties:
                  type:
                    type: string
                  data:
                    type: string

WebSocket​

WebSocket utilise x-protocol: "websocket" avec un bloc x-websocket. L'URL doit commencer par ws:// ou wss://.

paths:
  /ws:
    get:
      x-protocol: websocket
      x-websocket:
        url: wss://example.com/ws
        subprotocols: []
        headers: {}
      responses:
        "200":
          description: Operation response

subprotocols et headers sont optionnels.

GraphQL​

GraphQL utilise post sur un chemin de la forme /graphql/query/fieldName avec x-graphql. L'endpoint est une URL HTTP(S) absolue et la query est obligatoire.

paths:
  /graphql/query/product:
    post:
      x-protocol: graphql
      x-graphql:
        endpoint: https://example.com/graphql
        query: query Product($id: ID!) { product(id: ID!) { id name } }
        operationName: Product
        variablesSchema:
          type: object
        variables: {}
      responses:
        "200":
          description: Operation response

operationName, variablesSchema et variables sont optionnels.

gRPC​

gRPC utilise post sur un chemin de la forme /grpc/pkg.Service/Method avec x-grpc. Si le serveur supporte la réflexion, mettez reflection: true ; sinon fournissez protoPaths (et includeDirs optionnel).

paths:
  /grpc/products.ProductService/GetProduct:
    post:
      x-protocol: grpc
      x-grpc:
        address: host:port
        service: products.ProductService
        method: GetProduct
        kind: unary
        reflection: true
      responses:
        "200":
          description: Operation response

kind vaut unary, server_streaming, client_streaming ou bidi_streaming.

MCP​

MCP utilise par défaut le Streamable HTTP, post sur un chemin de la forme /mcp/tools/tool-name, avec un bloc x-mcp.

paths:
  /mcp/tools/create-product:
    post:
      x-protocol: mcp
      x-mcp:
        endpoint: http://127.0.0.1:3000/mcp
        transport: streamable-http
        method: tools/call
        name: create-product
        argumentsSchema:
          type: object
        arguments: {}
      responses:
        "200":
          description: Operation response

method choisit l'opération MCP : tools/call, tools/list, resources/read, resources/list, resources/templates/list, prompts/get, prompts/list. name, uri, argumentsSchema et arguments s'emploient selon la méthode.

Règles structurelles​

  • Pour les contrats générés par l’assistant, indiquez schema ou $ref pour les types de média dans requestBody ou responses. text/event-stream utilise itemSchema d’OAS 3.2 pour chaque événement. Il s’agit d’une convention de rédaction Powerduck, pas d’une obligation universelle pour tous les documents OpenAPI.
  • Chaque paramètre nécessite schema (ou content).
  • Quand vous éditez une opération, le protocole et la configuration choisis sont préservés : les opérations RPC ou streaming ne se convertissent pas silencieusement en REST.
  • Utilisez les formes d'extension exactes ci-dessus ; n'inventez pas de clés comme externalUrl et n'utilisez pas ws comme nom de protocole.

Pourquoi ça compte​

En modélisant sept protocoles dans un seul document, la conception, le débogage, la simulation, la documentation et MCP sont pilotés par la même source, quel que soit le transport. Demandez à l'assistant d'ajouter une interface de streaming ou RPC, et sa configuration de protocole reste intacte au lieu d'être aplatie en REST.

Voir aussi : Concevoir avec l'assistant、Modèle de données.

A2A​

A2A 1.0 permet le débogage et la documentation de JSON-RPC, REST et gRPC sur ordinateur, ainsi que la génération d’un serveur adaptateur de messages sans état. Les tâches persistantes et la livraison push nécessitent votre propre implémentation.

Utilisez x-protocol: a2a et x-a2a pour concevoir, déboguer et documenter messages et tâches. A2A 1.0 prend en charge JSON-RPC, REST et gRPC sur ordinateur ; 0.3 utilise JSON-RPC. Consultez Agents A2A pour les extensions, la vérification des signatures, la génération de serveur et la démo exécutable.