JSON trong REST API

JSON thường được sử dụng để trao đổi dữ liệu giữa client và server trong REST API. Dữ liệu có thể được gửi từ client đến server thông qua request body, hoặc được server trả về client thông qua response body.

Request Body và Response Body

Request Body là phần nội dung của HTTP request, thường chứa dữ liệu mà client gửi lên server. Ví dụ, khi muốn tạo một sản phẩm mới, client có thể gửi request POST /products với nội dung JSON như sau:

{
  "name": "Keyboard",
  "price": 500000
}

Response Body là phần nội dung của HTTP response, thường chứa dữ liệu mà server trả về cho client. Sau khi tạo sản phẩm thành công, server có thể trả về HTTP response với mã trạng thái 201 Created và thông tin sản phẩm vừa được tạo:

{
  "id": 10,
  "name": "Keyboard",
  "price": 500000
}

Trong ví dụ trên, client gửi tên và giá sản phẩm lên server. Sau khi tạo sản phẩm thành công, server trả về dữ liệu bao gồm cả id được gán cho sản phẩm.

Content-Type

Content-Type là một HTTP header dùng để cho biết định dạng của dữ liệu trong phần body của request hoặc response.

Khi nội dung được gửi dưới dạng JSON, header này thường có giá trị:

Content-Type: application/json

Header này giúp phía nhận biết cách diễn giải nội dung được gửi đi. Chẳng hạn, khi client gửi JSON lên server, Content-Type: application/json cho biết nội dung request body được định dạng theo JSON.

Như vậy, JSON đóng vai trò biểu diễn dữ liệu được trao đổi giữa client và server, trong khi HTTP Status Code cho biết kết quả xử lý yêu cầu. Đây là hai thành phần thường xuyên xuất hiện khi làm việc với REST API.

Tuy nhiên, REST API không bắt buộc phải sử dụng JSON. JSON chỉ là một trong những định dạng phổ biến được lựa chọn để trao đổi dữ liệu.

HTTP status code là gì?

HTTP Status Code (mã trạng thái HTTP) là mã gồm ba chữ số được gửi trong HTTP response để cho biết kết quả của request. Các mã này được chia thành năm nhóm chính, tương ứng với các phản hồi thông tin, thành công, chuyển hướng, lỗi phía client và lỗi phía server.

Các mã trạng thái được chia thành năm nhóm chính.

1xx — Informational (Thông tin)

Cho biết quá trình xử lý request vẫn đang tiếp diễn.

• 100 Continue: cho biết client có thể tiếp tục gửi phần còn lại của request.

2xx — Success (Thành công)

Cho biết request đã được xử lý thành công theo ý nghĩa của từng mã trạng thái.

• 200 OK: request được xử lý thành công.
• 201 Created: request đã dẫn đến việc tạo tài nguyên mới.
• 204 No Content: request được xử lý thành công nhưng response không có body.

3xx — Redirection (Chuyển hướng)

Cho biết client có thể cần thực hiện thêm hành động để hoàn tất việc truy cập hoặc sử dụng tài nguyên đã lưu.

• 301 Moved Permanently: tài nguyên đã được chuyển vĩnh viễn sang địa chỉ khác.
• 302 Found: tài nguyên tạm thời được cung cấp tại địa chỉ khác.
• 304 Not Modified: tài nguyên chưa thay đổi so với bản đã lưu, cho phép client sử dụng dữ liệu trong bộ nhớ đệm.

Với các mã chuyển hướng như 301 và 302, trình duyệt thường có thể tự động gửi request tiếp theo đến địa chỉ được chỉ định trong header Location.

4xx — Client Error (Lỗi phía yêu cầu)

Cho biết request có vấn đề hoặc không thể được thực hiện theo yêu cầu hiện tại.

• 400 Bad Request: request không hợp lệ.
• 401 Unauthorized: request chưa có thông tin xác thực hợp lệ.
• 403 Forbidden: server từ chối thực hiện yêu cầu.
• 404 Not Found: không tìm thấy tài nguyên được yêu cầu.
• 405 Method Not Allowed: method không được hỗ trợ cho tài nguyên đó.
• 429 Too Many Requests: client đã gửi quá nhiều request trong một khoảng thời gian.

5xx — Server Error (Lỗi phía server)

Cho biết server gặp lỗi hoặc không thể hoàn thành request tại thời điểm xử lý.

• 500 Internal Server Error: server gặp lỗi nội bộ.
• 502 Bad Gateway: gateway hoặc proxy nhận được phản hồi không hợp lệ từ server phía sau.
• 503 Service Unavailable: server tạm thời không thể xử lý yêu cầu, chẳng hạn do quá tải hoặc bảo trì.
• 504 Gateway Timeout: gateway hoặc proxy không nhận được phản hồi kịp thời từ server phía sau.

Status code giúp lập trình viên xác định hướng kiểm tra lỗi. Tuy nhiên, để tìm nguyên nhân cụ thể, cần kết hợp với log, thông tin từ ứng dụng và trạng thái của các dịch vụ liên quan.

Ví dụ về HTTP Status Code trong REST API

Khi làm việc với REST API, HTTP Status Code giúp client biết kết quả xử lý request. Dưới đây là một số trường hợp thường gặp khi xây dựng API quản lý sản phẩm.

1. 200 OK — Truy vấn thành công

Client gửi request để lấy thông tin sản phẩm có ID là 10:

GET /products/10 HTTP/1.1
Host: example.com

Nếu tìm thấy sản phẩm, server trả về HTTP response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 10,
  "name": "Keyboard",
  "price": 500000
}

200 OK cho biết request đã được xử lý thành công. Response body chứa thông tin sản phẩm dưới dạng JSON.

2. 201 Created — Tạo tài nguyên thành công

Client gửi request để tạo một sản phẩm mới:

POST /products HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "name": "Mouse",
  "price": 200000
}

Nếu tạo sản phẩm thành công, server có thể trả về:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 11,
  "name": "Mouse",
  "price": 200000
}

201 Created cho biết request đã dẫn đến việc tạo tài nguyên mới. Trong ví dụ này, server trả về thông tin sản phẩm vừa được tạo, bao gồm cả id.

3. 404 Not Found — Không tìm thấy tài nguyên

Client gửi request để lấy thông tin sản phẩm có ID là 99:

GET /products/99 HTTP/1.1
Host: example.com

Nếu sản phẩm không tồn tại, server có thể trả về:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "message": "Product not found"
}

404 Not Found cho biết server không tìm thấy tài nguyên tương ứng với request. Response body chứa thông báo giải thích lỗi do API thiết kế.

Qua các ví dụ trên, có thể thấy HTTP Status Code và response body đảm nhiệm hai vai trò khác nhau: status code cho biết kết quả của request, còn response body có thể chứa dữ liệu hoặc thông tin bổ sung. Cấu trúc response body cụ thể phụ thuộc vào thiết kế của API.

Kết luận

JSON và HTTP Status Codes là hai kiến thức cơ bản khi làm việc với REST API. JSON cung cấp định dạng để biểu diễn và trao đổi dữ liệu giữa client và server, trong khi HTTP Status Code cho biết kết quả xử lý của một request.

Việc hiểu cách JSON được tổ chức, cách dữ liệu được truyền qua request và response, cũng như ý nghĩa của các mã trạng thái sẽ giúp lập trình viên dễ dàng hơn trong việc xây dựng, sử dụng và xử lý lỗi khi làm việc với API.

Đây là nền tảng để tiếp tục tìm hiểu cách xây dựng REST API trong thực tế, từ việc tiếp nhận request, xử lý dữ liệu đến trả về response phù hợp.

Nguồn tham khảo

• JSON là gì? Cách lấy dữ liệu từ file JSON

• HTTP là gì (series HTTP & HTTPS)