Overzicht GraphQL API

Elk project in Archie Core maakt gebruik van een uniform API-eindpunt. Dit enkele eindpunt verwerkt GraphQL-queries, mutaties en abonnementen voor elke datatabel. De API is voorgeconfigureerd met filtering, paginering, full-text search en andere geavanceerde functies.

Alle API-verzoeken worden verzonden naar de volgende URL:

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

Om het verzoek naar uw specifieke project te routeren, moet u de header x-project-id met uw project-ID opnemen in elk HTTP-verzoek.

Velden Begrijpen

GraphQL is een specificatie voor het opvragen van velden op objecten. Hier is een eenvoudige Archie Core-query die zoekt naar een specifieke stad op basis van zijn unieke id, en vraagt om de velden nameCity en state terug te geven.

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

En hier is het resultaat:

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

Het resultaat heeft dezelfde vorm als de query. Dit is de sleutel tot GraphQL: je krijgt altijd waar je om vraagt, en de server weet welke velden de client opvraagt.

Archie Core GraphQL-queries zijn interactief en ondersteunen relationele queries native. Dit betekent twee belangrijke dingen:

1. Een query kan op elk moment worden gewijzigd.
2. Gerelateerde data kan worden samengevoegd zonder complexe databasequeries en serializers te schrijven.

Argumenten Begrijpen

De kracht van de Archie Core GraphQL API wordt verder verrijkt door de mogelijkheid om verschillende argumenten op te geven bij het uitvoeren van een query. Dit is aangetoond in het bovenstaande voorbeeld, waar een specifieke UUID-string als argument aan de query wordt doorgegeven (...citiesById(id: "e14638cb...")).

Bij het maken van datatabellen in de Data Builder, kan elk veld dat is gemarkeerd als uniek worden gebruikt als argument voor een query.

Bijvoorbeeld, aangezien de tabel Cities het veld ID als uniek heeft ingesteld (omdat het de primaire sleutel is), kunnen we vervolgens een specifiek City-record opvragen:

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

Variabelen

U kunt queries herbruikbaar en dynamisch maken door variabelen te gebruiken in de API Explorer.

Om met variabelen te werken, moet u:

1. De statische waarde in de query vervangen door de $variableName.
2. De $variableName declareren als een van de variabelen die door de query worden geaccepteerd.
3. variableName: value doorgeven in de aparte variabelen-dictionary.

Hier is de query:

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

Hier is de variabele:

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

En dit is het resultaat:

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

Aliassen

Aliassen worden gebruikt om objecten terug te geven met andere namen dan hun veldnamen. Dit is nodig bij het ophalen van hetzelfde type objecten met verschillende argumenten in één query.

Hieronder ziet u dat de eerste stad een alias “cityOne” heeft:

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

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

Resultaat:

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

Fragmenten

Queries kunnen lang en complex worden. Fragmenten creëren een set velden die kunnen worden gebruikt om de gedefinieerde set weer te geven. Als u meerdere velden van twee verschillende auteurs wilt, kunt u een fragment gebruiken in plaats van de velden twee keer te herhalen. In deze query hebben we een fragment genaamd { ...studentFrag }, dat meerdere velden bevat:

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

Het resultaat:

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