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

คุณกําลังดูเอกสาร Apigee Edge
ดูเอกสารประกอบเกี่ยวกับ Apigee X

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

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

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

OpenAPI Specification คืออะไร


"OpenAPI Initiative (OAI) มุ่งเน้นที่การสร้าง พัฒนา และโปรโมตรูปแบบคําอธิบาย API กลางของผู้ให้บริการตามข้อกําหนดเฉพาะ Swagger" โปรดดูข้อมูลเพิ่มเติมเกี่ยวกับโครงการริเริ่ม OpenAPI ที่ https://openapis.org

เอกสาร OpenAPI ใช้รูปแบบมาตรฐานเพื่ออธิบาย API ของ RESTful ไม่ว่าจะเป็นเอกสารในรูปแบบ JSON หรือ YAML เอกสารของ OpenAPI ก็อ่านได้ง่าย และยังทําให้มนุษย์อ่านและทําความเข้าใจอีกด้วย ข้อกําหนด 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

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