Panoramica API GraphQL

Ogni progetto in Archie Core utilizza un endpoint API unificato. Questo singolo endpoint gestisce query, mutazioni e sottoscrizioni GraphQL per ogni tabella dati. L’API è preconfigurata con filtraggio, impaginazione, ricerca full-text e altre funzionalità avanzate.

Tutte le richieste API vengono inviate al seguente URL:

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

Per instradare la richiesta al tuo progetto specifico, devi includere l’intestazione x-project-id contenente il tuo ID progetto in ogni richiesta HTTP.

Comprendere i Campi

GraphQL è una specifica per richiedere campi sugli oggetti. Ecco una semplice query Archie Core che cerca una città specifica tramite il suo id univoco, e richiede che vengano restituiti i campi nameCity e state.

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

Ed ecco il risultato:

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

Il risultato ha la stessa forma della query. Questa è la chiave di GraphQL: ottieni sempre ciò che chiedi, e il server sa quali campi il client sta richiedendo.

Le query GraphQL di Archie Core sono interattive e supportano nativamente le query relazionali. Questo significa due cose importanti:

1. Una query può essere modificata in qualsiasi momento.
2. I dati correlati possono essere uniti senza scrivere query di database e serializzatori complessi.

Comprendere gli Argomenti

La potenza dell’API GraphQL di Archie Core è ulteriormente arricchita dalla capacità di specificare diversi argomenti durante l’esecuzione di una query. Questo è stato dimostrato nell’esempio sopra, dove una specifica stringa UUID viene passata come argomento alla query (...citiesById(id: "e14638cb...")).

Quando si creano tabelle dati nel Data Builder, qualsiasi campo contrassegnato come univoco può quindi essere utilizzato come argomento per una query.

Ad esempio, poiché la tabella Cities ha il campo ID impostato come univoco (essendo la Chiave Primaria), possiamo quindi interrogare uno specifico record City:

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

Variabili

Puoi rendere le query riutilizzabili e dinamiche utilizzando le variabili nell’API Explorer.

Per lavorare con le variabili, devi:

1. Sostituire il valore statico nella query con $variableName.
2. Dichiarare il $variableName come una delle variabili accettate dalla query.
3. Passare variableName: value nel dizionario delle variabili separato.

Ecco la query:

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

Ecco la variabile:

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

Ed ecco il risultato:

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

Gli alias vengono utilizzati per restituire oggetti con nomi diversi dai loro nomi di campo. Questo è necessario quando si recupera lo stesso tipo di oggetti con argomenti diversi in una singola query.

Di seguito puoi vedere che la prima città ha un alias di “cityOne”:

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

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

Risultato:

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

Frammenti

Le query possono diventare lunghe e complesse. I frammenti creano un insieme di campi che possono essere utilizzati per rappresentare l’insieme definito. Se volessi più campi da due autori diversi, puoi utilizzare un frammento, invece di ripetere i campi due volte. In questa query, abbiamo un frammento chiamato { ...studentFrag }, che contiene più campi:

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

Il risultato:

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