Visão Geral da API GraphQL

Cada projeto no Archie Core utiliza um ponto de extremidade de API unificado. Este único ponto de extremidade lida com consultas, mutações e assinaturas GraphQL para cada tabela de dados. A API vem pré-configurada com filtragem, paginação, pesquisa de texto completo e outros recursos avançados.

Todas as solicitações de API são enviadas para o seguinte URL:

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

Para rotear a solicitação para o seu projeto específico, você deve incluir o cabeçalho x-project-id contendo seu ID de projeto em cada solicitação HTTP.

Entendendo os Campos

GraphQL é uma especificação para solicitar campos em objetos. Aqui está uma consulta simples do Archie Core que procura uma cidade específica por seu id exclusivo e solicita que os campos nameCity e state sejam retornados.

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

E aqui está o resultado:

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

O resultado tem a mesma forma que a consulta. Esta é a chave para o GraphQL: você sempre obtém o que pede, e o servidor sabe quais campos o cliente está solicitando.

As consultas GraphQL do Archie Core são interativas e suportam consultas relacionais nativamente. Isso significa duas coisas importantes:

1. Uma consulta pode ser alterada a qualquer momento.
2. Dados relacionados podem ser unidos sem escrever consultas complexas de banco de dados e serializadores.

Entendendo os Argumentos

O poder da API GraphQL do Archie Core é ainda mais enriquecido pela capacidade de especificar diferentes argumentos ao executar uma consulta. Isso foi demonstrado no exemplo acima, onde uma string UUID específica está sendo passada como um argumento para a consulta (...citiesById(id: "e14638cb...")).

Ao criar tabelas de dados no Data Builder, qualquer campo marcado como exclusivo pode então ser usado como um argumento para uma consulta.

Por exemplo, como a tabela Cities tem o campo ID definido como exclusivo (pois é a Chave Primária), podemos consultar um registro City específico:

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

Variáveis

Você pode tornar as consultas reutilizáveis e dinâmicas usando variáveis no API Explorer.

Para trabalhar com variáveis, você precisa:

1. Substituir o valor estático na consulta por $variableName.
2. Declarar o $variableName como uma das variáveis aceitas pela consulta.
3. Passar variableName: value no dicionário de variáveis separado.

Aqui está a consulta:

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

Aqui está a variável:

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

E este é o 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"
        }
      ]
    }
  }
}

Aliases

Aliases são usados para retornar objetos com nomes diferentes de seus nomes de campo. Isso é necessário ao buscar o mesmo tipo de objetos com argumentos diferentes em uma única consulta.

Abaixo você pode ver que a primeira cidade tem um 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

As consultas podem se tornar longas e complexas. Fragmentos criam um conjunto de campos que podem ser usados para representar o conjunto definido. Se você quisesse vários campos de dois autores diferentes, poderia usar um fragmento, em vez de repetir os campos duas vezes. Nesta consulta, temos um fragmento chamado { ...studentFrag }, que contém vários 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
      }
    }

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