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

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

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

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

ส่วนต่อไปนี้จะให้ข้อมูลเพิ่มเติมเกี่ยวกับเอกสาร OpenAPI และ GraphQL รวมถึงบทบาทของเอกสารเหล่านี้ในวงจรของ API หากต้องการเปรียบเทียบตัวเลือกการออกแบบ API ทั้ง 2 แบบ โปรดดู 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 ที่กําหนดจุดแรกเข้าของข้อมูล (ประเภทการค้นหา) การดำเนินการเขียนที่ใช้ได้ (ประเภทการเปลี่ยนแปลง) และประเภทข้อมูล

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 โดยสแนปชอตดังกล่าวแสดงถึงการแก้ไขเอกสารคำอธิบายที่เฉพาะเจาะจงในร้านค้าข้อมูลจำเพาะ