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

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

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

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

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

מהו מפרט OpenAPI?


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

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

הנה קטע ממסמך OpenAPI שמתאר את הדוגמה הפשוטה של 'hello World' של Apigee. לקבלת מידע נוסף, אפשר לעיין במפרט 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, מפיתוח ועד פרסום ומעקב.

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

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

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

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

אפשר ליצור שרת proxy ל-API ממסמך OpenAPI, כפי שמתואר בסעיפים הבאים:

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