סקירת GraphQL API

כל פרויקט ב-Archie Core משתמש ב-נקודת קצה API מאוחדת. נקודת הקצה האחת הזו מטפלת בשאילתות GraphQL, מוטציות ומנויים לכל טבלת נתונים. ה-API מגיע מוגדר מראש עם סינון, עימוד, חיפוש טקסט מלא ותכונות מתקדמות נוספות.

כל בקשות ה-API נשלחות לכתובת URL הבאה:

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

כדי לכוון את הבקשה לפרויקט הספציפי שלך, יש לכלול את כותרת x-project-id המכילה את מזהה הפרויקט שלך בכל בקשת HTTP.

הבנת שדות

GraphQL הוא מפרט לבקשת שדות על אובייקטים. הנה שאילתת Archie Core פשוטה המחפשת עיר מסוימת לפי ה-id הייחודי שלה, ומבקשת להחזיר את השדות nameCity ו-state.

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

והנה התוצאה:

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

לתוצאה יש את אותה צורת השאילתה. זהו המפתח של GraphQL: תמיד תקבל את מה שתובע, והשרת יודע אילו שדות הלקוח מבקש.

שאילתות Archie Core GraphQL הן אינטראקטיביות ותומכות בשאילתות יחסיות באופן מובנה. זה אומר שני דברים חשובים:

1. ניתן לשנות את השאילתה בכל עת.
2. ניתן לקשר נתונים קשורים ללא כתיבת שאילתות מסד נתונים מורכבות ומסורכזות.

הבנת פרמטרים

כוחה של Archie Core GraphQL API גובר ביכולת לציין פרמטרים שונים בעת ביצוע שאילתה. זה מודגם בדוגמה למעלה, שם מועברת מחרוזת UUID ספציפית כפרמטר לשאילתה (...citiesById(id: "e14638cb...")).

בעת יצירת טבלאות נתונים ב-Data Builder, ניתן להשתמש בכל שדה שמוגדר כ-ייחודי כפרמטר לשאילתה.

לדוגמה, מכיוון שלטבלה Cities יש שדה ID שמוגדר כייחודי (כיוון שהוא המפתח הראשי), נוכל לשאול את רשומת City ספציפית:

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

משתנים

ניתן להפוך שאילתות לניתנות לשימוש חוזר ודינמיות באמצעות משתנים ב-API Explorer.

כדי לעבוד עם משתנים, יש צורך:

1. להחליף את הערך הקבוע בשאילתה ב-$variableName.
2. להצהיר על $variableName כאחד משתני השאילתה המקובלים.
3. להעביר variableName: value במילון המשתנים הנפרד.

הנה השאילתה:

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

הנה המשתנה:

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

וזו התוצאה:

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

כינויים

כינויים משמשים להחזרת אובייקטים בשמות שונים משמות השדות שלהם. זה נדרש בעת קבלת אותו סוג אובייקטים עם פרמטרים שונים בשאילתה אחת.

להלן ניתן לראות שהעיר הראשונה יש לה כינוי “cityOne”:

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

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

התוצאה:

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

פרגמנטים

שאילתות יכולות להפוך לארוכות ומורכבות. פרגמנטים יוצרים קבוצת שדות שניתן להשתמש בה לייצוג הקבוצה המסוימת. אם תרצה כמה שדות ממחברים שונים, תוכל להשתמש בפרגמנט, במקום לחזור על השדות פעמיים. בשאילתה זו, יש לנו פרגמנט בשם { ...studentFrag }:

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

התוצאה:

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