סקירה כללית על עיצוב 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 מסוג RESTful. מסמך 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. במפרט מופיעים תיאורים מפורטים של רכיבי הסכימה וסוגי הנתונים.

יש מספר דוגמאות של מסמכי 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. תמונת המצב הזו מייצגת גרסה ספציפית של מסמך התיאור.