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 sẽ xác định các yêu cầu cho API của mình. Là một nhà thiết kế API, bạn lên kế hoạch cho các dịch vụ bạn muốn hiển thị cho người tiêu dùng và thiết kế các API để truy cập các dịch vụ đó. Bạn cần tạo một trong những giấy tờ sau để thể hiện các yêu cầu đối với API của mình:
- 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 các tài liệu này trong vòng đời của API. Để so sánh hai tùy chọn thiết kế API, hãy xem phần so sánh REST và GraphQL trong bài đăng trên blog này.
Thông số kỹ thuật OpenAPI là gì?
"OpenAPI Initiative (OAI) tập trung vào việc tạo, phát triển và thúc đẩy Định dạng mô tả API trung lập với nhà cung cấp dựa trên Thông số kỹ thuật 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 người dùng. 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.
Mời bạn xem 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 Thông số kỹ thuậ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 hữu ích về Quy cách OpenAPI. Bạn nên bắt đầu bằng trang web OpenAPI Initiative. Tại đây, bạn sẽ tìm thấy thông tin tổng quan, blog và đường liên kết đến Thông số kỹ thuật của OpenAPI. Hãy tham khảo phần Quy cách để biết nội dung mô tả chi tiết về các phần tử của giản đồ và loại 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.
Giản đồ GraphQL là gì?
Giản đồ GraphQL mô tả dữ liệu có trong API của bạn để ứng dụng truy vấn.
Lợi ích của việc 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 cho 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 bạn cần, ngăn chặn việc tìm nạp quá mức hoặc tìm nạp quá mức dữ liệu
- Xử lý các truy vấn diễn ra song song
Để biết thêm thông tin về GraphQL, hãy xem graphql.org.
Sau đây là ví dụ về giản đồ GraphQL xác định điểm nhập dữ liệu (loại Truy vấn), các thao tác ghi có sẵn (loại Chuyển đổi) và 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.
Đ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. Bạn sử dụng cùng một tài liệu ở mỗi giai đoạn trong vòng đời của API, từ phát triển đến phát hành rồi 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ẽ chịu ảnh hưởng trong tương lai:
- Nếu chỉnh sửa tài liệu, bạn cần 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 đó, đồng thời tạo lại tài liệu tham khảo API để phản ánh các thay đổi được triển khai trong tài liệu.
- Nếu xoá một tài liệu, bạn cần xoá các cấu phần phần mềm có liên quan, bao gồm cả proxy API theo cách thủ công 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à các tài nguyên của tài liệu đó.
Điều gì xảy ra khi tôi tạo proxy API 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 lượt nhấp là bạn sẽ có một proxy API chứa 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ư mô tả trong các phần sau:
- Từ danh sách thông số kỹ thuật, như mô tả trong Tạo proxy API từ thông số kỹ thuật trong danh sách thông số kỹ thuật. Lưu ý: Danh sách thông số kỹ thuật không có trong Classic Edge.
- Từ trình quản lý proxy API bằng cách gọi Trình hướng dẫn proxy bản dựng và chọn tạo proxy API của bạn từ tài liệu OpenAPI, như mô tả trong phần Sử dụng thông số kỹ thuật OpenAPI để tạo proxy.
Khi xuất bản API, bạn sẽ chụp nhanh thông tin tổng quan nhanh của tài liệu OpenAPI để tạo tài liệu tham khảo API. Ảnh chụp nhanh đó đại diện cho một bản sửa đổi cụ thể của tài liệu mô tả trong kho lưu trữ thông số kỹ thuật.