Aperçu de l'API GraphQL

Chaque projet dans Archie Core utilise un point de terminaison API unifié. Ce point de terminaison unique gère les requêtes GraphQL, les mutations et les abonnements pour chaque table de données. L’API est préconfigurée avec le filtrage, la pagination, la recherche en texte intégral et d’autres fonctionnalités avancées.

Toutes les demandes API sont envoyées à l’URL suivante :

https://archie-core.services.archie.com/graphql

Pour router la demande vers votre projet spécifique, vous devez inclure l’en-tête x-project-id contenant votre ID de projet dans chaque requête HTTP.

Comprendre les Champs

GraphQL est une spécification pour demander des champs sur des objets. Voici une requête Archie Core simple qui recherche une ville spécifique par son id unique, et demande que les champs nameCity et state soient retournés.

query MyQuery {
  citiesById(id: "e14638cb-6d72-4a36-b30f-9b763136a7bb") {
    id
    nameCity
    state
  }
}

Et voici le résultat :

{
  "data": {
    "citiesById": {
      "id": "e14638cb-6d72-4a36-b30f-9b763136a7bb",
      "nameCity": "Chicago",
      "state": "Illinois"
    }
  }
}

Le résultat a la même forme que la requête. C’est la clé de GraphQL : vous obtenez toujours ce que vous demandez, et le serveur sait quels champs le client demande.

Les requêtes GraphQL d’Archie Core sont interactives et prennent en charge les requêtes relationnelles de manière native. Cela signifie deux choses importantes :

1. Une requête peut être modifiée à tout moment.
2. Les données connexes peuvent être jointes sans écrire de requêtes de base de données et de sérialiseurs complexes.

Comprendre les Arguments

La puissance de l’API GraphQL d’Archie Core est encore enrichie par la capacité de spécifier différents arguments lors de l’exécution d’une requête. Cela a été démontré dans l’exemple ci-dessus, où une chaîne UUID spécifique est passée comme argument à la requête (...citiesById(id: "e14638cb...")).

Lors de la création de tables de données dans le Data Builder, tout champ marqué comme unique peut ensuite être utilisé comme argument pour une requête.

Par exemple, puisque la table Cities a le champ ID défini comme unique (car c’est la Clé Primaire), nous pouvons alors interroger un enregistrement City spécifique :

query MyQuery {
  citiesById(id: "e14638cb-6d72-4a36-b30f-9b763136a7bb") {
    id
    nameCity
    state
  }
}

Variables

Vous pouvez rendre les requêtes réutilisables et dynamiques en utilisant des variables dans l’API Explorer.

Pour travailler avec des variables, vous devez :

1. Remplacer la valeur statique dans la requête par $variableName.
2. Déclarer la $variableName comme l’une des variables acceptées par la requête.
3. Passer variableName: value dans le dictionnaire de variables séparé.

Voici la requête :

query MyQuery ($filter: StudentsFilter) {
  students(filter: $filter) {
    items {
      firstName
      email
    }
  }
}

Voici la variable :

{
  "filter": {
    "isActive": {
      "equals": true
    }
  }
}

Et voici le résultat :

{
  "data": {
    "students": {
      "items": [
        {
          "firstName": "James",
          "email": "james.smith@example.com"
        },
        {
          "firstName": "John",
          "email": "john.williams@example.com"
        },
        {
          "firstName": "Mary",
          "email": "mary.brown@example.com"
        },
        {
          "firstName": "Mary",
          "email": "mary.johnson@example.com"
        },
        {
          "firstName": "Elizabeth",
          "email": "elizabeth.davis@example.com"
        }
      ]
    }
  }
}

Alias

Les alias sont utilisés pour retourner des objets ayant des noms différents de leurs noms de champs. Cela est nécessaire lors de la récupération du même type d’objets avec des arguments différents dans une seule requête.

Ci-dessous, vous pouvez voir que la première ville a un alias de “cityOne” :

query MyQuery {
  cityOne: citiesById(id: "e14638cb-6d72-4a36-b30f-9b763136a7bb") {
    id
    nameCity
  }

  cityTwo: citiesById(id: "0174dc55-d494-4ebc-a0e9-13575461cad4") {
    id
    nameCity
  }
}

Résultat :

{
  "data": {
    "cityOne": {
      "id": "e14638cb-6d72-4a36-b30f-9b763136a7bb",
      "nameCity": "Chicago"
    },
    "cityTwo": {
      "id": "0174dc55-d494-4ebc-a0e9-13575461cad4",
      "nameCity": "Miami"
    }
  }
}

Fragments

Les requêtes peuvent devenir longues et complexes. Les fragments créent un ensemble de champs qui peuvent être utilisés pour représenter l’ensemble défini. Si vous vouliez plusieurs champs de deux auteurs différents, vous pouvez utiliser un fragment, au lieu de répéter les champs deux fois. Dans cette requête, nous avons un fragment appelé { ...studentFrag }, qui contient plusieurs champs :

query MyQuery {
  studentA: studentsById(id: "287cff0a-345b-4cca-9e9a-75a2161238fd") { ...studentFrag}

  studentB: studentsById(id: "97fb89ac-e0ad-44f5-b671-24a1b751287c") { ...studentFrag}
}

fragment studentFrag on Students {
      id
      firstName
      email
      isActive
      city {
        nameCity
        state
      }
    }

Le résultat :

{
  "data": {
    "studentA": {
      "id": "287cff0a-345b-4cca-9e9a-75a2161238fd",
      "firstName": "James",
      "email": "james.smith@example.com",
      "isActive": true,
      "city": {
        "nameCity": "Chicago",
        "state": "Illinois"
      }
    },
    "studentB": {
      "id": "97fb89ac-e0ad-44f5-b671-24a1b751287c",
      "firstName": "John",
      "email": "john.williams@example.com",
      "isActive": true,
      "city": {
        "nameCity": "Seattle",
        "state": "Washington"
      }
    }