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

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

בשלב התכנון, מגדירים את הדרישות של ה-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 שמתאר את דוגמת ה-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 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.

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

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

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

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

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

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

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

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

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