Assistant des Schémas Apollo Connectors

Outils MCP

Si les outils GraphOS MCP sont disponibles, utilisez-les :

connectors-spec : Récupérez la spécification complète des Connectors avant de commencer tout travail sur un connector
apollo_docs_search : Recherchez la documentation pertinente
apollo_docs_read : Lisez des pages de documentation spécifiques par slug

Chemins de documentation par sujet :

Requêtes : /graphos/connectors/requests/url, /headers, /body, /batching
Réponses : /graphos/connectors/responses/fields, /error-handling
Mapping : /graphos/connectors/mapping, /arrays, /enums, /literals
Entités : /graphos/connectors/entities, /patterns

Processus

Suivez ce processus en 5 étapes. NE SAUTEZ AUCUNE ÉTAPE.

Étape 1 : Recherche

[ ] Comprenez l'API appelée et la structure des réponses
[ ] Demandez à l'utilisateur des exemples de réponses API s'ils ne sont pas fournis
[ ] Récupérez la documentation pertinente via les outils MCP ou les fichiers de référence
[ ] NE ÉCRIVEZ AUCUN CODE jusqu'à ce que la recherche soit terminée

Étape 2 : Implémentation

[ ] Créez le schéma en utilisant le template ci-dessous
[ ] Suivez la grammaire, les méthodes et les variables des fichiers de référence
[ ] Posez des questions de clarification si vous avez des doutes sur les exigences

Étape 3 : Validation (Composition)

[ ] Exécutez rover supergraph compose --config ./supergraph.yaml
[ ] Corrigez les erreurs de composition avant de continuer

Étape 4 : Exécution

[ ] Exécutez rover connector run --schema <file> -c "<Type.field>" -v "{}"
[ ] Vérifiez que le connector s'exécute correctement

Étape 5 : Test

[ ] Créez ou mettez à jour les fichiers de test sous /tests/
[ ] Exécutez rover connector test
[ ] Assurez-vous une couverture de test complète pour chaque connector

Template de Schéma

# Note to AI Friends: This is an Apollo Connectors schema. You should use your connectors-spec MCP tool if you have it available before editing this file.

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.12")
  @link(url: "https://specs.apollo.dev/connect/v0.3", import: ["@source", "@connect"])

@source(name: "api_name", http: { baseURL: "https://api.example.com" })

type Query {
  example(id: ID!): Example
    @connect(
      source: "api_name"
      http: { GET: "/example/{$args.id}" }
      selection: """
      id
      name
      """
    )
}

type Example {
  id: ID!
  name: String
}

Exigences de version : Utilisez toujours federation/v2.12 et connect/v0.3 sauf indication contraire.

Fichiers de Référence

Avant d'implémenter les connectors, lisez les fichiers de référence pertinents :

Grammar - Syntaxe EBNF du mapping de sélection
Methods - Méthodes de transformation disponibles
Variables - Variables de mapping disponibles
Entities - Motifs d'entités et batching
Validation - Commandes Rover pour la validation
Troubleshooting - Erreurs courantes et solutions

Règles Clés

Selection Mapping

Préférez les sous-sélections à ->map pour un mapping plus propre
N'UTILISEZ PAS $ lors de la sélection directe de champs à partir de la racine
Aliasing de champ : newName: originalField (seulement lors du renommage)
Sous-sélection : fieldName { ... } (pour mapper du contenu imbriqué)

# BON - Sous-sélection directe pour les tableaux
$.results {
  firstName: name.first
  lastName: name.last
}

# MAUVAIS - $ racine inutile
$ {
  id
  name
}

# BON - Sélection directe de champ
id
name

Entités

Ajoutez @connect sur un type pour en faire une entité (pas besoin de @key)
Créez des stubs d'entités dans les sélections parentes : user: { id: userId }
Quand vous voyez un champ ID (p. ex. productId), créez une relation d'entité
Chaque entité doit avoir UN subgraph autoritaire avec @connect

Valeurs Littérales

Utilisez le wrapper $() pour les valeurs littérales dans les mappings :

$(1)              # nombre
$(true)           # booléen
$("hello")        # chaîne
$({"a": "b"})     # objet

# Dans le body
body: "$({ a: $args.a })"  # CORRECT
body: "{ a: $args.a }"     # MAUVAIS - ne se composera pas

Headers

http: {
  GET: "/api"
  headers: [
    { name: "Authorization", value: "Bearer {$env.API_KEY}" },
    { name: "X-Forwarded", from: "x-client" }
  ]
}

Batching

Convertissez les motifs N+1 en utilisant $batch :

type Product @connect(
  source: "api"
  http: {
    POST: "/batch"
    body: "ids: $batch.id"
  }
  selection: "id name"
) {
  id: ID!
  name: String
}

Règles Fondamentales

NE JAMAIS inventer de syntaxe ou de valeurs de directive absentes de cette spécification
NE JAMAIS utiliser --elv2-license accept (réservé aux humains)
TOUJOURS demander des exemples de réponses API avant d'écrire du code
TOUJOURS valider avec rover supergraph compose après les modifications
TOUJOURS créer des relations d'entités quand vous voyez des champs ID
Préférez $env à $config pour les variables d'environnement
Utilisez rover dev pour exécuter Apollo Router localement

apollo-connectors