ภาพรวมของการออกแบบ 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 ใช้รูปแบบมาตรฐานเพื่ออธิบาย RESTful API เอกสาร 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 มีดังนี้

  • ปลายทางเดียวจะให้สิทธิ์เข้าถึงช่องทั้งหมดในการดำเนินการที่กำหนด
  • ภาษาการค้นหาที่ทรงพลังที่เรียกว่า "ภาษาของคําจํากัดความของสคีมา" ช่วยให้คุณเข้าถึงข้อมูลที่ต้องการได้จริงๆ เพื่อป้องกันการดึงข้อมูลมากเกินไปหรือน้อยเกินไป
  • การประมวลผลคำค้นหาจะเกิดขึ้นพร้อมกัน

ดูข้อมูลเพิ่มเติมเกี่ยวกับ GraphQL ได้ที่ graphql.org

รายการต่อไปนี้แสดงตัวอย่างของสคีมา GraphQL ที่กำหนดจุดแรกเข้าของข้อมูล (ประเภทการค้นหา), การดำเนินการเขียนที่ใช้ได้ (ประเภท Mutation) และประเภทข้อมูล

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 เพื่อแสดงผลข้อมูลที่ต้องการในรูปแบบเพย์โหลด JSON ได้

การค้นหาและผลลัพธ์ของ GraphQL

จะเกิดอะไรขึ้นหากฉันแก้ไขเอกสาร

เอกสาร OpenAPI หรือ GraphQL แต่ละฉบับจะทำหน้าที่เป็นแหล่งข้อมูลที่ถูกต้องตลอดวงจรของ API เอกสารเดียวกันจะใช้ในแต่ละระยะในวงจรของ API ตั้งแต่การพัฒนา การเผยแพร่ ไปจนถึงการตรวจสอบ

การแก้ไขหรือลบเอกสารจะมีผลในภายหลัง ดังนี้

  • หากแก้ไขเอกสาร คุณจะต้องแก้ไขอาร์ติแฟกต์ที่เกี่ยวข้องด้วยตนเอง ซึ่งรวมถึงพร็อกซี API และผลิตภัณฑ์ API ที่แสดงทรัพยากร และสร้างเอกสารอ้างอิง API ใหม่เพื่อแสดงการเปลี่ยนแปลงที่นำมาใช้ในเอกสาร
  • หากลบเอกสาร คุณต้องลบอาร์ติแฟกต์ที่เกี่ยวข้อง ซึ่งรวมถึงพร็อกซี API ด้วยตนเอง และแก้ไขผลิตภัณฑ์ API เพื่อลบทรัพยากรที่เกี่ยวข้อง และสร้างเอกสารอ้างอิง API ขึ้นมาใหม่เพื่อให้สอดคล้องกับการนำเอกสารและทรัพยากรในเอกสารนั้นออก

จะเกิดอะไรขึ้นเมื่อฉันสร้างพร็อกซี API จากเอกสาร OpenAPI

ใน Edge คุณสร้างพร็อกซี API จากเอกสาร OpenAPI ได้ เพียงไม่กี่คลิก คุณก็จะได้พร็อกซี API ที่มีเส้นทาง พารามิเตอร์ โฟลว์แบบมีเงื่อนไข และปลายทางเป้าหมายที่สร้างขึ้นโดยอัตโนมัติ จากนั้นคุณจะเพิ่มฟีเจอร์ต่างๆ เช่น การรักษาความปลอดภัย OAuth, การจำกัดอัตรา และการแคชได้

คุณสามารถสร้างพร็อกซี API จากเอกสาร OpenAPI ดังที่อธิบายไว้ในส่วนต่อไปนี้

เมื่อเผยแพร่ API คุณจะต้องถ่ายสแนปชอตของเอกสาร OpenAPI เพื่อสร้างเอกสารอ้างอิง API สแนปชอตดังกล่าวแสดงการแก้ไขที่เฉพาะเจาะจงของเอกสารคำอธิบายในที่เก็บข้อมูลจำเพาะ