Kiến thức cơ bản về Endpoint
Tạo Endpoint
APIs, hãy nhấp vào nút New Endpoint.1.
2.
3.
4.
5.
Chế độ Design-first
Chế độ Request-first
Các chế độ giao diện
Đường dẫn Endpoint
/users). Base URL được thiết lập trong môi trường, và Apidog sẽ tự động thêm nó khi thực hiện yêu cầu đến endpoint./. Điều này giúp thiết kế API của bạn sạch sẽ, có tổ chức và bảo đảm bạn tận dụng đầy đủ các tính năng của Apidog.Tại sao nên bắt đầu đường dẫn bằng /
/ để tuân thủ OAS. Việc không bắt đầu đường dẫn bằng / có thể dẫn đến nhiều vấn đề tương thích khi sử dụng các công cụ trong hệ sinh thái OpenAPI./ ở đầu đường dẫn cho phép sử dụng chức năng mock mẫu URL, vốn cần thiết cho mục đích kiểm thử và xác thực trong Apidog.Phương thức yêu cầu
| Phương thức | Mô tả |
|---|---|
| GET | Truy xuất các tài nguyên được chỉ định mà không gây tác dụng phụ. Sử dụng tham số truy vấn để truyền dữ liệu. |
| POST | Gửi dữ liệu để xử lý và có thể gây tác dụng phụ. Dữ liệu thường được gửi trong body của yêu cầu. |
| PUT | Cập nhật hoặc thay thế toàn bộ các tài nguyên được chỉ định. |
| DELETE | Xóa các tài nguyên được chỉ định. |
| OPTIONS | Truy vấn các phương thức HTTP được tài nguyên đích hỗ trợ. |
| HEAD | Tương tự GET, nhưng chỉ truy xuất các header của phản hồi. Hữu ích để kiểm tra sự tồn tại và thay đổi của tài nguyên mà không cần tải xuống nội dung tài nguyên. |
| PATCH | Cập nhật một phần thông tin của các tài nguyên được chỉ định. |
| TRACE | Trả về yêu cầu mà máy chủ đã nhận. Chủ yếu được sử dụng cho mục đích gỡ lỗi và chẩn đoán. |
| CONNECT | Thiết lập một đường hầm đến máy chủ, thường được sử dụng để chuyển tiếp yêu cầu qua máy chủ proxy. |
Siêu dữ liệu Endpoint
| Trường | Mô tả |
|---|---|
| Name | Tên mô tả nêu rõ chức năng của endpoint. |
| Status | Trạng thái mặc định là "Developing". Bạn có thể sửa đổi trạng thái này để phản ánh các giai đoạn khác nhau như Testing hoặc Production. Tìm hiểu thêm về Trạng thái endpoint. |
| Maintainer | Chỉ định thành viên nhóm Apidog chịu trách nhiệm cho endpoint. Chọn một người dùng từ tài khoản của bạn để gán vai trò này. |
| Tags | Từ khóa hoặc cụm từ dùng để phân loại hoặc mô tả endpoint. Bạn có thể tạo thẻ mới hoặc chọn từ các thẻ hiện có. |
| Service | Base URL mà đường dẫn endpoint được nối vào. Theo mặc định được đặt là "Inherit from parents", nhưng có thể được chỉ định thủ công thông qua cài đặt môi trường. Tìm hiểu thêm về Môi trường và dịch vụ. |
| OperationId | Một mã định danh duy nhất (operationId trong OAS) dùng để phân biệt thao tác này trong API. |
| Description | Thông tin chi tiết về mục đích và cách sử dụng endpoint, hỗ trợ Markdown để định dạng nâng cao. |
Trường tùy chỉnh
Yêu cầu
Tham số yêu cầu
Query Parameters
?, và được phân tách bằng & như sau: ?id=2&status=available. Chúng được dùng để lọc, sắp xếp hoặc sửa đổi đầu ra của một API endpoint.INFO
Path Parameters
/pets/{id}, Ví dụ sai: /pets/:id.{parameter} trong URL, sau đó sử dụng {{variable}} cho giá trị tham số. Ví dụ:Khuyến nghị: Đặt biến trong giá trị path parameter
Không khuyến nghị: Đặt biến trực tiếp trong URL
Không nhầm lẫn {parameter} và {{variable}}
{parameter}: Dấu ngoặc nhọn đơn biểu thị path parameters trong Apidog. Path parameters là các phần giữ chỗ trong đường dẫn URL, thay đổi động thành các giá trị cụ thể khi API endpoint được truy cập.{{variable}}: Dấu ngoặc nhọn kép bao gồm các biến trong yêu cầu. Các biến này có thể được thay thế bằng giá trị thực khi yêu cầu được gửi, cho phép đầu vào động và có thể tùy chỉnh trong các tương tác API.Tại sao KHÔNG nên sử dụng {{variable}} trong đường dẫn
{{variable}} không tuân thủ OAS. Tuân theo OAS cho phép tích hợp liền mạch với nhiều công cụ trong hệ sinh thái OpenAPI.{{variable}} trong đường dẫn sẽ ngăn sử dụng chức năng mock mẫu URL trong Apidog.Header Parameters
Tìm hiểu thêm
Body Parameters
Tìm hiểu thêm
Mô tả tham số
| Thuộc tính | Mô tả |
|---|---|
| Name | Chỉ định tên của tham số đang được mô tả. Đây là trường bắt buộc và nên đại diện chính xác cho tham số đang được định nghĩa. |
| Type | Chỉ định kiểu dữ liệu của giá trị tham số. Các giá trị phổ biến bao gồm string, number, integer, boolean, array, object, và nhiều giá trị khác. Thuộc tính này giúp định nghĩa định dạng và cấu trúc của giá trị tham số. |
| Description | Cung cấp giải thích hoặc tài liệu ngắn gọn về tham số. Thuộc tính này giúp người dùng hiểu mục đích và cách sử dụng tham số. |
| Required | Chỉ định liệu tham số có bắt buộc đối với yêu cầu API hay không. Đây là giá trị boolean (true hoặc false) cho biết tham số có phải được bao gồm trong yêu cầu hay không. |
| Advanced Settings | Định nghĩa kiểu dữ liệu, định dạng và các ràng buộc của tham số. Thuộc tính này cho phép bạn cung cấp thông tin chi tiết về cấu trúc và nội dung mong đợi của giá trị tham số. |
Type Editor
Schemas
JSON hoặc XML, cần thiết lập cấu trúc dữ liệu. Cấu trúc dữ liệu có thể tham chiếu đến schemas.Tìm hiểu thêm
Phản hồi và ví dụ
| Thành phần | Mô tả |
|---|---|
| HTTP Status Code | Xác định tất cả các trạng thái phản hồi tiềm năng mà endpoint của bạn có thể trả về, bao gồm các phản hồi tiêu chuẩn như 200 (OK), 404 (Not Found), hoặc 500 (Server Error). |
| Data Format | Định nghĩa định dạng của phản hồi mà API sẽ trả về cho từng mã trạng thái. Định dạng này có thể là JSON, XML, HTML, Raw, Binary, hoặc bất kỳ định dạng phù hợp nào khác. |
| Schema | Đối với các phản hồi mang dữ liệu (chủ yếu là trạng thái 200), hãy nêu chi tiết cấu trúc của payload phản hồi. Điều này bao gồm việc chỉ định kiểu, đối tượng lồng nhau, trường tùy chọn và mảng. Các định nghĩa rõ ràng giúp nhà phát triển client hiểu dữ liệu cần mong đợi và cách phân tích dữ liệu đó. Chỉ JSON và XML mới có thể cấu hình schemas. Để biết thông tin chi tiết, xem Schemas. |
| Example | Việc cung cấp phản hồi ví dụ là điều cần thiết để minh họa cách API hoạt động trong các tình huống thực tế. Một ví dụ lý tưởng nên là tập dữ liệu mẫu được máy chủ trả về khi endpoint được gọi bằng một yêu cầu đã định nghĩa trước. Ví dụ đó nên phản ánh cấu trúc, định dạng dữ liệu và các kiểu như đã được định nghĩa bởi schema của phản hồi. |
Thêm phản hồi
200 OK thường khác nhau giữa nhiều endpoint do nhu cầu dữ liệu đầu ra riêng biệt, các phản hồi lỗi như 400 Bad Request và 404 Not Found có xu hướng nhất quán giữa các endpoint khác nhau. Apidog xử lý điểm chung này một cách thông minh bằng tính năng Response Component, cho phép tái sử dụng các phản hồi lỗi đã định nghĩa trước, giúp quy trình lập tài liệu API hiệu quả hơn và hành vi API nhất quán hơn.Response Components
Thêm ví dụ phản hồi
Tạo ví dụ tự động
Xem trước Endpoint
Modified at 2026-06-11 10:23:06