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

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X. מידע

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

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

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

מהו המפרט של OpenAPI?


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

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

הנה קטע ממסמך OpenAPI שמתאר את דוגמת עולם שלום פשוטה של 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 Specification.

מהי סכימת GraphQL?

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

בין יתרונות השימוש ב-ChartQL:

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

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

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

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

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