Übersicht über die GraphQL-API

Jedes Projekt in Archie Core nutzt einen einheitlichen API-Endpunkt. Dieser einzelne Endpunkt behandelt GraphQL-Abfragen, Mutationen und Abonnements für jede Datentabelle. Die API ist vorkonfiguriert mit Filterung, Paginierung, Volltextsuche und anderen erweiterten Funktionen.

Alle API-Anfragen werden an die folgende URL gesendet:

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

Um die Anfrage an Ihr spezifisches Projekt weiterzuleiten, müssen Sie in jeder HTTP-Anfrage den Header x-project-id mit Ihrer Projekt-ID angeben.

Felder verstehen

GraphQL ist eine Spezifikation zum Anfordern von Feldern in Objekten. Hier ist eine einfache Archie Core-Abfrage, die nach einer bestimmten Stadt anhand ihrer eindeutigen id sucht und anfordert, dass die Felder nameCity und state zurückgegeben werden.

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

Und hier ist das Ergebnis:

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

Das Ergebnis hat die gleiche Form wie die Abfrage. Dies ist der Schlüssel zu GraphQL: Sie erhalten immer das, was Sie anfordern, und der Server weiß, welche Felder der Client anfordert.

Archie Core GraphQL-Abfragen sind interaktiv und unterstützen relationale Abfragen nativ. Das bedeutet zwei wichtige Dinge:

1. Eine Abfrage kann jederzeit geändert werden.
2. Verwandte Daten können ohne das Schreiben komplexer Datenbankabfragen und Serialisierer verbunden werden.

Argumente verstehen

Die Leistungsfähigkeit der Archie Core GraphQL-API wird durch die Möglichkeit bereichert, verschiedene Argumente beim Ausführen einer Abfrage anzugeben. Dies wurde im obigen Beispiel gezeigt, wo ein bestimmter UUID-String als Argument an die Abfrage übergeben wird (...citiesById(id: "e14638cb...")).

Beim Erstellen von Datentabellen im Data Builder kann jedes als eindeutig markierte Feld als Argument für eine Abfrage verwendet werden.

Da zum Beispiel die Tabelle Cities das Feld ID als eindeutig festgelegt hat (da es der Primärschlüssel ist), können wir dann einen bestimmten City-Datensatz abfragen:

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

Variablen

Sie können Abfragen wiederverwendbar und dynamisch machen, indem Sie Variablen im API Explorer verwenden.

Um mit Variablen zu arbeiten, müssen Sie:

1. Den statischen Wert in der Abfrage durch den $variableName ersetzen.
2. Den $variableName als eine der von der Abfrage akzeptierten Variablen deklarieren.
3. variableName: value im separaten Variablen-Wörterbuch übergeben.

Hier ist die Abfrage:

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

Hier ist die Variable:

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

Und das ist das Ergebnis:

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

Aliase

Aliase werden verwendet, um Objekte mit anderen Namen als ihren Feldnamen zurückzugeben. Dies ist erforderlich, wenn der gleiche Objekttyp mit unterschiedlichen Argumenten in einer einzigen Abfrage abgerufen wird.

Unten sehen Sie, dass die erste Stadt den Alias “cityOne” hat:

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

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

Ergebnis:

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

Fragmente

Abfragen können lang und komplex werden. Fragmente erstellen einen Satz von Feldern, die verwendet werden können, um den definierten Satz darzustellen. Wenn Sie mehrere Felder von zwei verschiedenen Autoren wollten, können Sie ein Fragment verwenden, anstatt die Felder zweimal zu wiederholen. In dieser Abfrage haben wir ein Fragment namens { ...studentFrag }, das mehrere Felder enthält:

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

Das Ergebnis:

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