GraphQL API Genel Bakış

Archie Core’daki her proje, birleşik bir API uç noktası kullanır. Bu tek uç nokta, her veri tablosu için GraphQL sorgularını, mutasyonlarını ve aboneliklerini işler. API, filtreleme, sayfalama, tam metin arama ve diğer gelişmiş özelliklerle önceden yapılandırılmış olarak gelir.

Tüm API istekleri aşağıdaki URL’ye gönderilir:

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

İsteği belirli projenize yönlendirmek için, her HTTP isteğine proje ID’nizi içeren x-project-id başlığını eklemelisiniz.

Alanları Anlamak

GraphQL, nesnelerdeki alanları istemek için bir spesifikasyondur. İşte belirli bir şehri benzersiz id’sine göre arayan ve nameCity ile state alanlarının döndürülmesini isteyen basit bir Archie Core sorgusu.

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

Ve işte sonuç:

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

Sonuç, sorgu ile aynı şekle sahiptir. Bu, GraphQL’in anahtarıdır: her zaman ne isterseniz onu alırsınız ve sunucu, istemcinin hangi alanları istediğini bilir.

Archie Core GraphQL sorguları etkileşimlidir ve ilişkisel sorguları yerel olarak destekler. Bu iki önemli anlama gelir:

1. Bir sorgu her zaman değiştirilebilir.
2. İlişkili veriler, karmaşık veritabanı sorguları ve serileştiriciler yazılmadan birleştirilebilir.

Argümanları Anlamak

Archie Core GraphQL API’sinin gücü, bir sorguyu çalıştırırken farklı argümanlar belirleme yeteneği ile daha da zenginleştirilmiştir. Bu, yukarıdaki örnekte, sorguya bir argüman olarak belirli bir UUID dizesinin geçirildiği yerde gösterilmiştir (...citiesById(id: "e14638cb...")).

Data Builder’da veri tabloları oluştururken, benzersiz olarak işaretlenen herhangi bir alan, bir sorgu için argüman olarak kullanılabilir.

Örneğin, Cities tablosunun ID alanı benzersiz olarak ayarlandığından (Birincil Anahtar olduğu için), belirli bir City kaydını sorgulayabiliriz:

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

Değişkenler

API Explorer’da değişkenleri kullanarak sorguları yeniden kullanılabilir ve dinamik hale getirebilirsiniz.

Değişkenlerle çalışmak için şunlara ihtiyacınız vardır:

1. Sorgudaki statik değeri $variableName ile değiştirin.
2. $variableName’i sorgu tarafından kabul edilen değişkenlerden biri olarak bildirin.
3. Ayrı değişkenler sözlüğünde variableName: value geçirin.

İşte sorgu:

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

İşte değişken:

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

Ve bu da sonuç:

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

Takma Adlar

Takma adlar, alan adlarından farklı adlara sahip nesneleri döndürmek için kullanılır. Bu, tek bir sorguda farklı argümanlarla aynı türdeki nesneleri getirirken gereklidir.

Aşağıda, ilk şehrin “cityOne” takma adına sahip olduğunu görebilirsiniz:

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

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

Sonuç:

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

Parçalar

Sorgular uzun ve karmaşık hale gelebilir. Parçalar, tanımlanan kümeyi temsil etmek için kullanılabilecek bir alan kümesi oluşturur. İki farklı yazardan birkaç alan isteseydiniz, alanları iki kez tekrarlamak yerine bir parça kullanabilirsiniz. Bu sorguda, birkaç alan içeren { ...studentFrag } adlı bir parçamız var:

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

Sonuç:

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