Visión General de la API GraphQL

Cada proyecto en Archie Core utiliza un punto final de API unificado. Este único punto final maneja consultas, mutaciones y suscripciones de GraphQL para cada tabla de datos. La API viene preconfigurada con filtrado, paginación, búsqueda de texto completo y otras características avanzadas.

Todas las solicitudes de API se envían a la siguiente URL:

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

Para enrutar la solicitud a su proyecto específico, debe incluir el encabezado x-project-id conteniendo su ID de proyecto en cada solicitud HTTP.

Entendiendo los Campos

GraphQL es una especificación para solicitar campos en objetos. Aquí hay una consulta simple de Archie Core que busca una ciudad específica por su id único, y solicita que se devuelvan los campos nameCity y state.

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

Y aquí está el resultado:

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

El resultado tiene la misma forma que la consulta. Esto es clave en GraphQL: siempre obtienes lo que pides, y el servidor sabe qué campos está solicitando el cliente.

Las consultas GraphQL de Archie Core son interactivas y soportan consultas relacionales de forma nativa. Esto significa dos cosas importantes:

1. Una consulta puede ser modificada en cualquier momento.
2. Los datos relacionados pueden unirse sin escribir consultas complejas de base de datos ni serializadores.

Entendiendo los Argumentos

El poder de la API GraphQL de Archie Core se enriquece aún más con la capacidad de especificar diferentes argumentos al ejecutar una consulta. Esto se ha demostrado en el ejemplo anterior, donde se pasa una cadena UUID específica como argumento a la consulta (...citiesById(id: "e14638cb...")).

Al crear tablas de datos en el Data Builder, cualquier campo marcado como único puede usarse como argumento para una consulta.

Por ejemplo, dado que la tabla Cities tiene el campo ID configurado como único (ya que es la Clave Primaria), podemos consultar un registro específico de City:

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

Variables

Puede hacer que las consultas sean reutilizables y dinámicas utilizando variables en el API Explorer.

Para trabajar con variables, necesita:

1. Reemplazar el valor estático en la consulta con el $variableName.
2. Declarar el $variableName como una de las variables aceptadas por la consulta.
3. Pasar variableName: value en el diccionario de variables separado.

Aquí está la consulta:

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

Aquí está la variable:

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

Y este es el resultado:

{
  "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

Los alias se utilizan para devolver objetos con nombres diferentes a sus nombres de campo. Esto es necesario cuando se obtiene el mismo tipo de objetos con diferentes argumentos en una sola consulta.

A continuación puede ver que la primera ciudad tiene 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
  }
}

Resultado:

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

Fragmentos

Las consultas pueden volverse largas y complejas. Los fragmentos crean un conjunto de campos que se pueden usar para representar el conjunto definido. Si quisiera varios campos de dos autores diferentes, puede usar un fragmento, en lugar de repetir los campos dos veces. En esta consulta, tenemos un fragmento llamado { ...studentFrag }, que contiene varios campos:

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
      }
    }

El resultado:

{
  "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"
      }
    }