API (RESTful API)

REST API là gì?

REST API (còn được biết với tên gọi RESTful API) là một giao diện lập trình ứng dụng (API) tuân thủ các ràng buộc và quy ước kiến trúc REST được sử dụng trong việc giao tiếp giữa client và server. REST là viết tắt của REpresentational State Transfer, nó được tạo ra bởi nhà khoa học máy tính Roy Fielding.

REST API thường vẫn sử dụng giao thức HTTP/1 kèm theo các định nghĩa trước đó mà cả client và server cần tuân thủ.

Hiện tại, các REST API dùng JSON rất phổ biến. Một ít có thể vẫn còn dùng XML.

Hai thành phần trong RESTful API

REST (REpresentational State Transfer) là một đại diện cho sự chuyển đổi dữ liệu. Trong kiến trúc này client và server hoàn toàn độc lập, chúng không biết gì về nhau. Mỗi một request REST API đều không mang theo trạng thái trước đó (stateless).

Như vậy để đôi bên trao đổi state, chúng sẽ phải thông qua các resources. Các resource này chính là phần đại diện cho sự thay đổi dữ liệu.

API (Application Programming Interface) là giao diện lập trình ứng dụng. Giao diện này không dành cho người dùng cuối mà dành cho các nhà phát triển (developer), chỉ thấy được phần khai báo (tên, tham số, kiểu trả về), không thấy body.

Request và Response trong REST API

Methods: Phương thức

Như đã đề cập ở trên, để trao đổi state chúng sẽ cần giao tiếp resource thông qua việc gởi các request response thông qua HTTP/1. Cụ thể việc giao tiếp này là thế nào thì chúng cần chỉ định các method tương ứng bao gồm:

• GET: Trả về một Resource hoặc một danh sách Resource.
• POST: Tạo mới một Resource.
• PUT: Cập nhật thông tin cho Resource (toàn bộ resource).
• PATCH: Cật nhật thông tin cho resourse (một phần resource).
• DELETE: Xoá một Resource.

Nếu bạn từng nghe qua CRUD APIs thì chúng đại diện cho Create, Read, Update và Delete một resource nào đó.

Header: Authentication và quy định kiểu dữ liệu trả về

Hãy nhớ rằng REST API là stateless. Mỗi một request không hề biết bất kỳ thông tin gì trước đó. Khác với khi chúng ta truy cập web, trình duyệt sẽ có session và cookie để hỗ trợ phân biệt request đấy là của ai, thông tin trước đó là gì.

Trong REST, nếu một request cần xác thực quyền truy cập, chúng sẽ phải dùng thêm thông tin trong header. Ví dụ như thông tin Authorization sẽ mang theo một user token. Hiện có 3 cơ chế Authentication chính:

• HTTP Basic
• JSON Web Token (JWT)
• OAuth2

Ngoài ra Header còn giúp client chỉ định được loại content cần trả về từ server – content type. Việc này được thực hiện thông qua phần Accept trong header. Giá trị của nó thường là MIME type:

• image — image/png, image/jpeg, image/gif
• audio — audio/wav, audio/mpeg
• video — video/mp4, video/ogg
• application — application/json, application/pdf, application/xml, application/octet-stream

Ví dụ request lấy danh sách bài viết:

GET /v1/posts

Accept: application/json

Status Code trong RESTful API

Response trong REST API sẽ bao gồm một status code quy định cụ thể từng trường hợp.

Một số status phổ biến:

• 200 OK – Trả về thành công cho những phương thức GET, PUT, PATCH hoặc DELETE.
• 201 Created – Trả về khi một Resouce vừa được tạo thành công.
• 204 No Content – Trả về khi Resource xoá thành công.
• 304 Not Modified – Client có thể sử dụng dữ liệu cache, resource server không đổi gì.
• 400 Bad Request – Request không hợp lệ
• 401 Unauthorized – Request cần có xác thực.
• 403 Forbidden – bị từ chối không cho phép.
• 404 Not Found – Không tìm thấy resource từ URI
• 405 Method Not Allowed – Phương thức không cho phép với user hiện tại.
• 410 Gone – Resource không còn tồn tại, Version cũ đã không còn hỗ trợ.
• 415 Unsupported Media Type – Không hỗ trợ kiểu Resource này.
• 422 Unprocessable Entity – Dữ liệu không được xác thực
• 429 Too Many Requests – Request bị từ chối do bị giới hạn

Hỗ trợ version của REST API

Thông thường REST API sẽ có version như /v1, /v2 để hỗ trợ các phiên bản dữ liệu cũ hơn. Việc này đặc biệt quan trọng khi chúng ta nâng cấp API lên các version cao hơn, sự nâng cấp này có thể khác biệt rất to lớn: thay đổi URL, cách thức xác thực người dùng hoặc cả resource name và cấu trúc của nó.

Cách thiết kế REST API theo convention

Cách thiết kế REST API theo convention

Mặc dù các ràng buộc và quy ước trên các nhà phát triển không cần tuân thủ. Tuy nhiên nếu làm “đúng”, chúng sẽ mang lại rất nhiều lợi ích.

Thiết kế REST API URI

Mình đã từng thấy rất nhiều REST API thiết kế viết đại khái như sau:

Text

POST /create_post (tạo bài viết)

GET /list_posts (lấy danh sách bài viết)

POST /feature_posts (danh sách bài viết nổi bật)

POST /edit_post/:post_id (edit bài viết với post_id)

Các REST API chưa được thiết kế tốt cho lắm

Những REST API này vẫn hoạt động tốt, không vấn đề gì cả!! Có điều chúng không theo convention mà thôi.

Việc này dẫn đến một rắc rối cho người làm document (hoặc chính người thiết kế ra) phải rà soát lại cái URL có chính xác không. Phía sử dụng API cũng phải thiết lập một danh sách API đúng như vậy luôn.

Các bạn hãy so sánh với thiết kế URL như sau:

Text

POST /v1/posts (tạo mới một bài viết)

GET /v1/posts (lấy danh sách bài viết)

GET /v1/posts/:post_id (lấy chi tiết bài viết với post_id cụ thể)

PUT /v1/posts/:post_id (update bài viết với post_id cụ thể)

DELETE /posts/:post_id (delete bài viết với post_id cụ thể)

Các REST API được thiết kế tốt hơn, đúng convention

Cách thiết kế này các bạn sẽ thấy rằng có một nguyên tắc rất rõ ràng sử dụng các method request để nói lên được nhiệm vụ của API. Phần URI có thể giống nhau, không cần cứ phải chứa các động từ như: create, get, update, delete nữa. Resource name sẽ ở dạng số nhiều (plural).

Một số ví dụ khác:

Text

GET /v1/posts/:post_id/liked-users (lấy danh sách user đã like bài viết với post_id cụ thể)

POST /v1/posts/:post_id/liked-users (like bài viết với post_id cụ thể)

GET /v1/posts?page=2&limit=50 (hãy dùng query string để filter hoặc phân trang nhé)

Các quy ước khác bạn cần chú ý

• Sử dụng đúng Status Code. Nếu API trả về lỗi, các bạn hãy dùng đúng status nhé, tránh luôn trả về status 2xx khi mà trong body là error message (cái này nhiều bạn đang làm sai lắm).
• Đừng dùng underscore (_), hãy dùng hyphen (-) trong URI
• Trong URI đều là chữ viết thường (lowercase)
• Đừng nên sử dụng đuôi file (extension) trong URI (VD: .html, .xml, .json).

Kết:

REST API là một kiểu kiến trúc phổ biến để xây dựng dịch vụ web, và việc thiết kế REST API theo các nguyên tắc chuẩn giúp đảm bảo tính nhất quán và dễ sử dụng của API.

Trong thực tế công nghệ ngày nay, REST API đã trở thành một phần không thể thiếu của việc xây dựng ứng dụng và dịch vụ trực tuyến. Với khả năng liên kết mạnh mẽ, tương tác hiệu quả và khả năng mở rộng linh hoạt, RESTful API thực sự đã thiết lập tiêu chuẩn cho việc trao đổi thông tin giữa các hệ thống khác nhau. Trong bối cảnh gia tăng của ứng dụng di động, dịch vụ web và IoT, kiến thức chắc về REST API đã trở thành một yếu tố quan trọng trong lĩnh vực phát triển phần mềm.

(https://200lab.io/blog/rest-api-la-gi/)

Bài viết khác

Golang

Golang là gì? Go hay còn gọi là Golang là ngôn ngữ lập trình mã nguồn mở, được thiết kế tại Google bởi Robert Griesemer, Rob Pike, and Ken Thompson. Go có cú pháp giống với C và tất nhiên nó là ngôn ngữ lập trình biên dịch (compiled programming language) Cú pháp của ngôn […]

Đọc thêm

Elasticsearch

Elasticsearch là gì? Elasticsearch là một search engine (công cụ tìm kiếm) rất mạnh mẽ. Elasticsearch cũng có thể coi là một document oriented database, nó chứa dữ liệu giống như một database và thực hiện tìm kiếm trên những dữ liệu đó. Đại khái là thay vì bạn tìm kiếm trên file, trên các […]

Đọc thêm

Testing

Testing là gì? Thường thì mọi người hiểu khái niệm test chỉ là chạy test, chạy phần mềm nhưng đó chỉ là một phần không phải tất cả các hoạt động test. Các hoạt động test tồn tại trước và sau khi chạy PM bao gồm: lên kế hoạch và kiểm soát, chọn điều kiện […]

Đọc thêm

Web Security

Có rất nhiều lý do để học về web security như: Bạn là một người dùng lo lắng về việc thông tin cá nhân bị rò rỉ. Bạn là một web developer muốn làm cho trang web của bạn bảo mật hơn. Bạn là một web developer đang tìm việc, và bạn muốn sẵn sàng […]

Đọc thêm

Cache

Trong vài năm trở lại đây, công nghệ thông tin đã trở thành bàn đạp cho sự cải thiện mạnh mẽ cho vô số các loại hình kinh doanh. Song song, kiến trúc của các phần mềm cũng ngày càng trở nên phức tạp và số lượng người dùng của chúng đã và đang tăng […]

Đọc thêm

Docker

Docker là gì? Docker là một nền tảng phần mềm giúp bạn building, deploying và running ứng dụng dễ dàng hơn bằng cách sử dụng các containers (trên nền tảng ảo hóa). Docker ban đầu Docker  được viết bằng PyDockerthon, hiện tại đã chuyển sang Golang. Docker đóng gói phần mềm thành các container tiêu […]

Đọc thêm