Tổng quan về thiết kế API

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến Tài liệu về Apigee X. thông tin

Trong giai đoạn Thiết kế, bạn xác định các yêu cầu cho API. Với tư cách là nhà thiết kế API, bạn lập kế hoạch các dịch vụ mà bạn muốn hiển thị cho người tiêu dùng và thiết kế API để truy cập các dịch vụ đó. Bạn tạo một trong các giấy tờ sau để thu thập các yêu cầu về API:

  • Tài liệu OpenAPI
  • Giản đồ GraphQL

Các phần sau đây cung cấp thêm thông tin về các tài liệu OpenAPI và GraphQL, cũng như vai trò của chúng trong vòng đời của API. Để so sánh hai lựa chọn thiết kế API, hãy xem so sánh REST và GraphQL trong bài đăng trên blog này.

Đặc tả OpenAPI là gì?


"Sáng kiến OpenAPI (OAI) tập trung vào việc tạo, phát triển và quảng bá Định dạng mô tả API trung lập cho nhà cung cấp dựa trên Quy cách của Swagger". Để biết thêm thông tin về Sáng kiến OpenAPI, hãy truy cập vào https://openapis.org.

Tài liệu OpenAPI sử dụng định dạng chuẩn để mô tả API RESTful. Được viết ở định dạng JSON hoặc YAML, tài liệu OpenAPI có thể đọc được bằng máy, nhưng cũng dễ đọc và dễ hiểu đối với con người. Thông số kỹ thuật OpenAPI cho phép mô tả chính thức các phần tử của API, chẳng hạn như đường dẫn cơ sở, đường dẫn và động từ, tiêu đề, tham số truy vấn, loại nội dung, mô hình phản hồi, v.v. Ngoài ra, tài liệu OpenAPI thường được dùng để tạo tài liệu API.

Đây là một đoạn trong tài liệu OpenAPI mô tả mẫu Hello world đơn giản của Apigee. Để biết thêm thông tin, hãy xem Đặc tả OpenAPI trên 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
...

Có nhiều nguồn thông tin tuyệt vời về Quy cách OpenAPI. Bạn nên bắt đầu bằng cách truy cập trang web OpenAPI Initiative, nơi bạn sẽ tìm thấy các bài viết tổng quan, blog và đường liên kết đến Đặc tả OpenAPI. Tham khảo Thông số kỹ thuật để biết nội dung mô tả chi tiết về các phần tử của giản đồ và kiểu dữ liệu.

Bạn có thể tải một số tài liệu OpenAPI mẫu JSON và YAML xuống từ Kho lưu trữ thông số kỹ thuật OpenAPI.

Schema GraphQL là gì?

Giản đồ GraphQL mô tả dữ liệu có sẵn trong API của bạn để ứng dụng truy vấn.

Sau đây là các lợi ích khi sử dụng GraphQL:

  • Một điểm cuối duy nhất cung cấp quyền truy cập vào tất cả các trường của một thao tác cụ thể
  • Ngôn ngữ truy vấn mạnh mẽ, được gọi là Ngôn ngữ định nghĩa giản đồ, cho phép bạn truy cập chính xác dữ liệu mình cần, ngăn việc tìm nạp quá mức hoặc tìm nạp ít dữ liệu
  • Quá trình xử lý truy vấn diễn ra song song

Để biết thêm thông tin về GraphQL, hãy truy cập vào graphql.org.

Sau đây là ví dụ về giản đồ GraphQL xác định điểm truy cập dữ liệu (Loại truy vấn), các thao tác ghi có sẵn (Loại đột biến) và các loại dữ liệu.

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!
}

Bạn có thể truy vấn giản đồ GraphQL để trả về dữ liệu chính xác mà bạn cần dưới dạng tải trọng JSON.

Truy vấn và kết quả trong GraphQL

Điều gì sẽ xảy ra nếu tôi sửa đổi một tài liệu?

Mỗi tài liệu OpenAPI hoặc GraphQL đóng vai trò là nguồn đáng tin cậy trong suốt vòng đời API. Sử dụng cùng một tài liệu ở mỗi giai đoạn trong vòng đời API, từ phát triển, xuất bản cho đến giám sát.

Khi bạn chỉnh sửa hoặc xoá một tài liệu, tài liệu đó sẽ có tác động về sau:

  • Nếu chỉnh sửa tài liệu, bạn cần phải chỉnh sửa thủ công các cấu phần phần mềm có liên quan, bao gồm proxy API và mọi sản phẩm API hiển thị tài nguyên của tài liệu đó và tạo lại tài liệu tham khảo API để phản ánh những thay đổi được triển khai trong tài liệu.
  • Nếu xoá tài liệu, bạn cần xoá các cấu phần phần mềm có liên quan theo cách thủ công, kể cả proxy API và chỉnh sửa bất kỳ sản phẩm API nào để xoá các tài nguyên có liên quan, đồng thời tạo lại tài liệu tham khảo API để phản ánh việc xoá tài liệu và tài nguyên của tài liệu đó.

Điều gì xảy ra khi tôi tạo proxy API từ một tài liệu OpenAPI?

Trong Edge, bạn có thể tạo proxy API từ các tài liệu OpenAPI của mình. Chỉ cần vài cú nhấp chuột, bạn sẽ có một proxy API với các đường dẫn, thông số, luồng có điều kiện và điểm cuối mục tiêu được tạo tự động. Sau đó, bạn có thể thêm các tính năng như bảo mật OAuth, giới hạn tốc độ và lưu vào bộ nhớ đệm.

Bạn có thể tạo proxy API từ tài liệu OpenAPI, như được mô tả trong các phần sau:

Khi xuất bản API, bạn sẽ chụp ảnh chụp nhanh tài liệu OpenAPI để tạo tài liệu tham khảo API. Bản tổng quan nhanh đó minh hoạ một bản sửa đổi cụ thể của tài liệu mô tả trong kho thông số kỹ thuật.