ภาพรวมของการออกแบบ API

คุณกำลังดูเอกสารประกอบของ Apigee Edge
ไปที่เอกสารประกอบของ Apigee X ข้อมูล

ในขั้นตอนการออกแบบ คุณจะได้ระบุข้อกำหนดสำหรับ API ของคุณ ในฐานะผู้ออกแบบ API คุณวางแผนบริการที่ต้องการแสดงต่อผู้บริโภค และออกแบบ API เพื่อเข้าถึงบริการเหล่านั้น คุณสร้างเอกสารอย่างใดอย่างหนึ่งต่อไปนี้เพื่อบันทึกข้อกําหนดของ API

  • เอกสาร OpenAPI
  • สคีมา GraphQL

ส่วนต่อไปนี้จะแสดงข้อมูลเพิ่มเติมเกี่ยวกับเอกสาร OpenAPI และ GraphQL รวมถึงบทบาทที่เอกสารเหล่านี้มีต่อวงจร API ของคุณ สำหรับการเปรียบเทียบตัวเลือกการออกแบบ API ทั้งสองแบบ โปรดดู REST และ GraphQL ที่เปรียบเทียบในบล็อกโพสต์นี้

ข้อกำหนดของ OpenAPI คืออะไร


"โครงการ OpenAPI Initiative (OAI) มุ่งเน้นที่การสร้าง พัฒนา และโปรโมตรูปแบบคำอธิบาย API ที่เป็นกลางของผู้ให้บริการตามข้อกำหนดของ Swribe" ดูข้อมูลเพิ่มเติมเกี่ยวกับโครงการริเริ่ม OpenAPI ได้ที่ 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 ได้แก่

  • ปลายทางเดียวให้สิทธิ์เข้าถึงช่องทั้งหมดสําหรับการดำเนินการที่ระบุ
  • ภาษาการค้นหาที่ทรงพลังเรียกว่า 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 เพื่อแสดงผลข้อมูลที่ต้องการในรูปแบบเพย์โหลด JSON ได้

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

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

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

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

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

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

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

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

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