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

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

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

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

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

מהו מפרט OpenAPI?


"יוזמת OpenAPI (OAI) מתמקדת ביצירה, התפתחות וקידום של פורמט תיאור API נייטרלי של ספקים על סמך מפרט Swagger". מידע נוסף על יוזמת OpenAPI זמין בכתובת 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. במפרט אפשר למצוא תיאורים מפורטים של רכיבי הסכימה וסוגי הנתונים.

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