Một API request sẽ nhận được 1 response tương ứng. Để đọc tài liệu API hoặc test bằng Postman, tester cần tách rõ từng thành phần của request và response.
Request
Request là toàn bộ thông tin client gửi tới server để yêu cầu thực hiện một hành động.
1. URL và endpoint
URL là địa chỉ đầy đủ được gọi. Endpoint thường được hiểu là sự kết hợp giữa HTTP method và đường dẫn cụ thể.
| Thành phần | Ví dụ |
|---|---|
| URL đầy đủ | https://api.elitest.vn/api/articles/xin-chao |
| Base URL | https://api.elitest.vn |
| Path | /api/articles/xin-chao |
| Endpoint | GET /api/articles/{slug} |
2. HTTP method
HTTP method là các phương thức để xem API muốn “đòi hỏi” gì từ server
| Method | Mục đích thường gặp | Ví dụ | Có cần gửi data theo không |
|---|---|---|---|
GET | Lấy dữ liệu | GET /api/articles | Không |
POST | Tạo mới hoặc thực hiện một hành động | POST /api/articles | Có |
PUT | Cập nhật resource | PUT | Có |
PATCH | Cập nhật một phần resource | PATCH | Có |
DELETE | Xoá resource | DELETE /api/articles/bai-viet-so-1 | Không |
3. Path parameter
Path parameter nằm ngay trong đường dẫn và thường dùng để xác định một resource cụ thể.
GET /api/articles/{slug}
GET /api/articles/xin-chaoTrong ví dụ trên, slug là tên parameter; xin-chao là giá trị thực tế. Nếu slug không tồn tại, server trả 404 Not Found.
4. Query parameter
Query parameter nằm sau dấu ?, thường dùng để lọc, tìm kiếm hoặc phân trang. Nhiều query parameter được nối bằng dấu &.
GET /api/articles?tag=testing&limit=5&offset=0| Parameter | Ý nghĩa |
|---|---|
tag=testing | Chỉ lấy bài có tag testing |
limit=5 | Lấy tối đa 5 bài |
offset=0 | Bắt đầu từ bản ghi đầu tiên |
5. Request headers
Headers chứa thông tin bổ sung về request. Chúng không phải dữ liệu nghiệp vụ chính nhưng giúp server biết client đang gửi loại dữ liệu nào và người gọi là ai.
| Header | Ví dụ | Ý nghĩa |
|---|---|---|
Authorization | Bearer <access_token> | Gửi token đăng nhập. Token đại diện cho người gửi request đó. Cú pháp thường là Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... |
Content-Type | application/json | Body đang được gửi dưới dạng JSON. Là kiểu phổ biến nhất. Ngoài ra có thể gửi dạng form hoặc file… |
Accept | application/json | Client mong muốn nhận JSON |
User-Agent | MyAppClient/1.0.0 | Thông tin về |
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
Accept: application/json
User-Agent: MyAppClient/1.0.06. Request body
Request body chứa dữ liệu client gửi lên. Không phải request nào cũng có body; GET thường không cần body, còn POST và PUT phải có.
POST /api/articles với body dạng JSON:{
"article": {
"title": "Học API Testing",
"description": "Bài viết thực hành",
"body": "Nội dung bài viết",
"tagList": ["api", "testing"]
}
}Trong body ở bên trên, chúng ta sẽ thấy đầy đủ các thông tin cần có để tạo ra 1 bài viết hoàn chỉnh
7. Authorization
Authorization là bước server kiểm tra người dùng đã đăng nhập và có được phép thực hiện hành động hay không. Nó liên quan đến header Authorization, nhưng hai khái niệm không hoàn toàn giống nhau:
- Header là nơi client gửi token.
- Authorization là quá trình server dùng danh tính và quyền của người dùng để cho phép hoặc từ chối hành động.
GET /api/articles có thể được gọi khi chưa đăng nhập. Nhưng
POST /api/articles cần token hợp lệ; người dùng cũng không được sửa hoặc xoá bài của người khác.Response
Response là toàn bộ kết quả server trả về sau khi xử lý request.
1. Status code
Status code cho biết kết quả tổng quát của request. Khi test, đừng chỉ kiểm tra “có trả về JSON hay không”; hãy kiểm tra cả mã trạng thái có đúng với tình huống hay không.
| Status | Ý nghĩa dễ hiểu | Ví dụ |
|---|---|---|
200 OK | Request thành công và có kết quả trả về | GET /api/articles |
201 Created | Tạo resource thành công | POST /api/articles |
204 No Content | Thành công nhưng không có response body | DELETE /api/articles/{slug} |
401 Unauthorized | Chưa đăng nhập, thiếu token hoặc token không hợp lệ | Gọi GET /api/user mà không gửi token |
403 Forbidden | Đã xác định được người dùng nhưng người đó không có quyền | Người dùng cố sửa hoặc xoá bài viết của người khác |
404 Not Found | Không tìm thấy resource | GET /api/articles/slug-khong-ton-tai |
422 Unprocessable Content | Request đúng cú pháp HTTP nhưng dữ liệu không hợp lệ | GET /api/articles?limit=0, trong khi limit phải từ 1 trở lên |
400 Bad Request | Request sai hoặc server không thể hiểu request | Khái niệm phổ biến; các lỗi validation của Playground hiện chủ yếu dùng 422 |
401: “Bạn là ai?” – server chưa xác thực được người dùng. 403: “Tôi biết bạn là ai, nhưng bạn không được làm việc này.”2. Response body
Response body chứa dữ liệu hoặc thông báo lỗi mà server trả về.
GET /api/articles?limit=1&offset=0 [200 SUCCEED]{
"articles": [
{
"slug": "xin-chao",
"title": "Xin chào",
"favorited": false,
"favoritesCount": 0
}
],
"articlesCount": 11
}{
"errors": {
"limit": ["Input should be greater than or equal to 1"]
}
}3. Response time
Response time là thời gian từ lúc client gửi request đến khi nhận đủ response. Postman hiển thị giá trị này theo millisecond, chẳng hạn 180 ms. Con số có thể thay đổi giữa các lần gọi do mạng, tải server, database và lượng dữ liệu trả về.
Ghép lại thành một request hoàn chỉnh
PUT https://api.elitest.vn/api/articles/hoc-api-testing
Authorization: Token <access_token>
Content-Type: application/json
Accept: application/json
{
"article": {
"description": "Nội dung đã được cập nhật"
}
}Trong request này:
PUTlà method;- URL xác định API cần gọi;
hoc-api-testinglà path parameter;- headers mô tả token và định dạng dữ liệu;
articlelà request body.- Server sẽ trả status code, response headers, response body và response time.
Xem thêm: API Testing (P1): API, Client–Server và REST API và API Testing: JSON và cách làm việc với nó.
