Bạn đang xem tài liệu về Apigee Edge.
Truy cập vào
tài liệu Apigee X. thông tin
Trong giai đoạn Thiết kế, bạn xác định các yêu cầu đối với API của mình. Là nhà thiết kế API, bạn lập kế hoạch cho các dịch vụ mà bạn muốn cung cấp cho người tiêu dùng và thiết kế API để truy cập vào các dịch vụ đó. Bạn tạo một trong các tài liệu sau để ghi lại các yêu cầu về API:
- Một tài liệu OpenAPI
- Một lược đồ GraphQL
Các phần sau đây cung cấp thêm thông tin về 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 2 lựa chọn thiết kế API, hãy xem bài đăng trên blog này để biết thông tin so sánh giữa REST và GraphQL.
Quy cách OpenAPI là gì?
"OpenAPI Initiative (OAI) tập trung vào việc tạo, phát triển và quảng bá Định dạng mô tả API độc lập với nhà cung cấp dựa trên Đặc tả Swagger." Để biết thêm thông tin về Sáng kiến OpenAPI, hãy xem https://openapis.org.
Tài liệu OpenAPI sử dụng một định dạng tiêu chuẩn để mô tả 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ễ dàng để con người đọc và hiểu. OpenAPI Specification cho phép mô tả chính thức các phần tử của một 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.
Sau đây là một đoạn mã 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 tuyệt vời về Quy cách OpenAPI. Bạn nên bắt đầu từ trang web của 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 Quy cách OpenAPI. Hãy tham khảo Quy cách để biết nội dung mô tả chi tiết về các phần tử giản đồ và kiểu dữ liệu.
Có một số tài liệu OpenAPI mẫu ở định dạng JSON và YAML mà bạn có thể tải xuống từ kho lưu trữ Đặc tả OpenAPI.
Schema GraphQL là gì?
Giản đồ GraphQL mô tả dữ liệu có trong API của bạn để một ứng dụng có thể 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 cho một thao tác nhất định
- Ngôn ngữ truy vấn mạnh mẽ (được gọi là Ngôn ngữ định nghĩa lược đồ) cho phép bạn truy cập chính xác vào dữ liệu bạn cần, ngăn chặn việc tìm nạp quá nhiều hoặc quá ít dữ liệu
- Quá trình 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ề một 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 Độ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ề chính xác dữ liệu bạn cần dưới dạng tải trọng JSON.
Điều gì 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 đều đóng vai trò là nguồn đáng tin cậy trong suốt vòng đời API. Bạn có thể 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 xuất bản rồi giám sát.
Khi bạn chỉnh sửa hoặc xoá một tài liệu, điều này sẽ ảnh hưởng đến các tài liệu khác:
- Nếu chỉnh sửa một 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 cả proxy API và mọi sản phẩm API hiển thị tài nguyên của proxy đó, đồng thời 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á 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 theo cách thủ công, bao gồm cả API proxy và chỉnh sửa mọi sản phẩm API để 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ì sẽ xảy ra khi tôi tạo một proxy API từ tài liệu OpenAPI?
Trong Edge, bạn có thể tạo các proxy API từ tài liệu OpenAPI. 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, tham 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 một 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 phần Tạo một proxy API từ mộ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 Edge phiên bản cũ.
- Từ trình quản lý proxy API bằng cách gọi Trình hướng dẫn tạo proxy và chọn tạo proxy API từ mộ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 ảnh chụp nhanh của tài liệu OpenAPI để tạo tài liệu tham khảo API. Ảnh chụp nhanh đó thể hiện 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.