Przegląd API GraphQL

Każdy projekt w Archie Core korzysta z zintegrowanego punktu końcowego API. Ten jeden punkt końcowy obsługuje zapytania, mutacje i subskrypcje GraphQL dla każdej tabeli danych. API jest wstępnie skonfigurowane z filtrowaniem, stronicowaniem, wyszukiwaniem pełnotekstowym i innymi zaawansowanymi funkcjami.

Wszystkie żądania API są wysyłane na następujący adres URL:

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

Aby skierować żądanie do konkretnego projektu, musisz dołączyć nagłówek x-project-id zawierający Twój identyfikator projektu w każdym żądaniu HTTP.

Zrozumienie Pól

GraphQL to specyfikacja żądania pól w obiektach. Oto proste zapytanie Archie Core, które szuka konkretnego miasta po jego unikalnym id i żąda zwrotu pól nameCity oraz state.

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

A oto wynik:

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

Wynik ma ten sam kształt co zapytanie. To klucz do GraphQL: zawsze otrzymujesz to, o co prosisz, a serwer wie, jakich pól żąda klient.

Zapytania GraphQL Archie Core są interaktywne i natywnie obsługują zapytania relacyjne. Oznacza to dwie ważne rzeczy:

1. Zapytanie można zmienić w dowolnym momencie.
2. Powiązane dane mogą być łączone bez pisania skomplikowanych zapytań do bazy danych i serializatorów.

Zrozumienie Argumentów

Moc API GraphQL Archie Core jest dodatkowo wzbogacona o możliwość określania różnych argumentów podczas wykonywania zapytania. Zostało to pokazane w powyższym przykładzie, gdzie konkretny ciąg UUID jest przekazywany jako argument do zapytania (...citiesById(id: "e14638cb...")).

Podczas tworzenia tabel danych w Data Builder, każde pole oznaczone jako unikalne może być następnie użyte jako argument dla zapytania.

Na przykład, ponieważ tabela Cities ma pole ID ustawione jako unikalne (ponieważ jest to klucz główny), możemy zapytać o konkretny rekord City:

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

Zmienne

Możesz sprawić, że zapytania będą wielokrotnego użytku i dynamiczne, używając zmiennych w API Explorer.

Aby pracować ze zmiennymi, musisz:

1. Zastąpić statyczną wartość w zapytaniu przez $variableName.
2. Zadeklarować $variableName jako jedną ze zmiennych akceptowanych przez zapytanie.
3. Przekazać variableName: value w osobnym słowniku zmiennych.

Oto zapytanie:

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

Oto zmienna:

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

A to jest wynik:

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

Aliasy

Aliasy są używane do zwracania obiektów o nazwach innych niż nazwy ich pól. Jest to potrzebne przy pobieraniu tego samego typu obiektów z różnymi argumentami w jednym zapytaniu.

Poniżej widać, że pierwsze miasto ma alias “cityOne”:

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

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

Wynik:

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

Fragmenty

Zapytania mogą stać się długie i skomplikowane. Fragmenty tworzą zestaw pól, które mogą być użyte do reprezentowania zdefiniowanego zestawu. Jeśli chciałbyś kilka pól od dwóch różnych autorów, możesz użyć fragmentu, zamiast powtarzać pola dwa razy. W tym zapytaniu mamy fragment o nazwie { ...studentFrag }, który zawiera kilka pól:

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

Wynik:

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