סקירה כללית על עיצוב API

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

בשלב התכנון, מגדירים את הדרישות של ה-API. כמעצבי API, אתם מתכננים את השירותים שאתם רוצים לחשוף לצרכנים ומעצבים ממשקי API כדי לגשת לשירותים האלה. יוצרים אחד מהמסמכים הבאים כדי לתעד את הדרישות של ה-API:

  • מסמך OpenAPI
  • סכימת GraphQL

בקטעים הבאים מוסבר בהרחבה על מסמכי OpenAPI ו-GraphQL ועל התפקיד שלהם במחזור החיים של ה-API. בפוסט הזה בבלוג יש השוואה בין שתי האפשרויות לעיצוב API – REST ו-GraphQL.

מהו מפרט OpenAPI?


"ה-OpenAPI Initiative (OAI) מתמקד ביצירה, בפיתוח ובקידום של פורמט ניטרלי לספק לתיאור API, שמבוסס על מפרט Swagger". מידע נוסף על OpenAPI Initiative זמין בכתובת https://openapis.org.

מסמך OpenAPI משתמש בפורמט סטנדרטי כדי לתאר API ל-REST. מסמך OpenAPI כתוב בפורמט JSON או YAML, והוא קריא למחשבים וגם קל לקריאה ולהבנה על ידי בני אדם. מפרט OpenAPI מאפשר תיאור רשמי של רכיבים ב-API, כמו נתיב הבסיס, הנתיבים והפעלים, הכותרות, פרמטרים של שאילתות, סוגי תוכן, מודלים של תגובות ועוד. בנוסף, בדרך כלל משתמשים במסמך OpenAPI כדי ליצור תיעוד של API.

בהמשך מוצג קטע ממסמך OpenAPI שמתאר את הדוגמה הפשוטה של Apigee ל-hello world. מידע נוסף זמין במפרט OpenAPI ב-GitHub.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

יש הרבה מקורות מידע מצוינים על מפרטי OpenAPI. מקום טוב להתחיל בו הוא האתר של OpenAPI Initiative, שבו אפשר למצוא סקירות כלליות, בלוגים וקישורים לOpenAPI Specification. במפרט מופיעים תיאורים מפורטים של רכיבי הסכימה וסוגי הנתונים.

יש מספר מסמכי OpenAPI לדוגמה בפורמט JSON ו-YAML שאפשר להוריד ממאגר מפרטי OpenAPI.

מהי סכימת GraphQL?

סכימת GraphQL מתארת את הנתונים שזמינים ב-API לשאילתות של לקוח.

היתרונות של שימוש ב-GraphQL כוללים:

  • נקודת קצה אחת מספקת גישה לכל השדות של פעולה נתונה
  • שפת השאילתות העוצמתית, שנקראת Schema Definition Language (שפת הגדרת סכימה), מאפשרת לכם לגשת בדיוק לנתונים שאתם צריכים, וכך להימנע מאחזור עודף או מאחזור חסר של נתונים
  • עיבוד השאילתות מתבצע במקביל

מידע נוסף על GraphQL זמין באתר graphql.org.

בהמשך מופיעה דוגמה לסכימת GraphQL שמגדירה את נקודת הכניסה לנתונים (סוג שאילתה), פעולות הכתיבה הזמינות (סוג מוטציה) וסוגי הנתונים.

type Query {
  Greeting: String
  students: [Student]
}
type Mutation {
  createStudent(firstName: String!, lastName: String!): Student!
}
type Subscription {
  newStudent: Student!
}
type Student {
  Id: ID!
  firstName: String!
  lastName: String!
  password: String!
  collegeId: String!
}

אפשר לשלוח שאילתה לסכימת GraphQL כדי להחזיר את הנתונים המדויקים שאתם צריכים כמטען ייעודי (payload) של JSON.

שאילתת GraphQL ותוצאות

מה קורה אם משנים מסמך?

כל מסמך OpenAPI או GraphQL משמש כמקור האמת לאורך מחזור החיים של ה-API. אותו מסמך משמש בכל שלב במחזור החיים של ה-API, החל משלב הפיתוח ועד לשלב הפרסום והמעקב.

כשעורכים או מוחקים מסמך, זה משפיע על דברים אחרים:

  • אם עורכים מסמך, צריך לערוך באופן ידני את הארטיפקטים שקשורים אליו, כולל ה-proxy ל-API וכל מוצר API שחושף את המשאבים שלו, וליצור מחדש את מאמרי העזרה של ה-API כדי לשקף את השינויים שהוטמעו במסמך.
  • אם מוחקים מסמך, צריך למחוק באופן ידני את הארטיפקטים שקשורים אליו, כולל ה-proxy ל-API, לערוך את כל מוצרי ה-API כדי למחוק את המשאבים שקשורים אליו, וליצור מחדש את מאמרי העזרה של ה-API כדי לשקף את ההסרה של המסמך והמשאבים שלו.

מה קורה כשיוצרים proxy ל-API ממסמך OpenAPI?

אפשר ליצור שרתי proxy ל-API ממסמכי OpenAPI. בכמה קליקים בלבד, תקבלו proxy ל-API עם הנתיבים, הפרמטרים, זרימות מותנות ונקודות קצה של יעד שנוצרו באופן אוטומטי. אחר כך תוכלו להוסיף תכונות כמו אבטחת OAuth, הגבלת קצב של יצירת בקשות וקירור מטמון.

אפשר ליצור שרת proxy ל-API ממסמך OpenAPI באמצעות אשף יצירת שרת proxy, כמו שמתואר במאמר שימוש במפרטי OpenAPI ליצירת שרתי proxy. כדי להתנסות בפועל, אפשר לעבור על המדריך יצירת proxy ל-API ממפרט OpenAPI.

כשמפרסמים את ה-API, יוצרים תמונת מצב של מסמך ה-OpenAPI כדי ליצור מאמרי עזרה ל-API. תמונת המצב הזו מייצגת גרסה ספציפית של מסמך התיאור.