STACKJAVA

Giới thiệu về RESTful Web Service, xây dựng RESTful Web-Service

Giới thiệu về RESTful Web Service, xây dựng RESTful Web-Service

Xem lại: Web service là gì?

Giới thiệu về RESTful Web Service, xây dựng RESTful Web-Service

1. Giới thiệu về RESTful Web Service

RESTful (REpresentational State Transfer) là một kiểu Web Service được viết dựa trên kiến trúc REST.
Các đặc điểm của RESTful web service:
  • Sử dụng các phương thức HTTP/HTTPs
  • Phi trạng thái (stateless) (không lưu trữ thông tin của client)
  • Hiển thị cấu trúc thư mục như các URls
  • Truyền tải dữ liệu với định dạng phong phú: html, json, text, xml… (thường sử dụng nhiều với json)

Ví dụ API của Facebook cũng là 1 dạng RESTful Web Service

Giới thiệu về RESTful Web Service, xây dựng RESTful Web-Service

2. Thiết kế RESTful Web Service

2.1 Dữ liệu trả về

RESTful Web Service hỗ trợ trả về dữ liệu với nhiều định dạng khác nhau: XML, JSON, HTML… tuy nhiên chúng ta chỉ nên dùng 1 loại để tránh sự phức tạp, rắc rối khi bảo trì hay giao tiếp với hệ thống khác

2.2 Các HTTP Method mà RESTful hỗ trợ

Mỗi hành động trong web service tương ứng với 1 request method của http:

  • Method GET: được sử dụng để truy vấn, lấy dữ liệu từ server. Request sử dụng method GET chỉ nên sủ dụng để lấy dữ liệu, không nên chỉnh sửa/tác động tới dữ liệu
  • Method HEAD: giống như method GET nhưng chỉ nhận về status và header, không nhận về body
  • Method POST: được sử dụng để gửi dữ liệu tới server, tạo mới tài nguyên, ví dụ upload file, đăng nhập…
  • Method PUT: được dùng để cập nhật cho tài nguyên (ví dụ update cả đối tượng user)
  • Method PATCH: giống như method PUT nhưng chỉ cập nhật cho 1 phần dữ liệu (ví dụ chỉ update thông tin 1 thuộc tính của user)
  • Method DELETE: được dùng cho hành động xóa đối tượng trên server.
  • Một số method khác: CONNECT, OPTIONS, TRACE

Với lập trình web, khi submit form ta hay sử dụng 2 method là GET, POST.
Với web service ta sẽ hay sử dụng 5 method là GET, POST, PUT, PATCH, DELETE.

Nếu bạn sử dụng lẫn lộn các method thì chương trình vẫn chạy (ví dụ dùng method POST để xóa dữ liệu…) tuy nhiên nó sẽ gây khó hiểu, không rõ ràng.

2.3 Định dạng dữ liệu JSON

Khi đặt tên biến ta thường đặt kiểu camel case ví dụ dateOfBirth hoặc kiểu snake case: date_of_birth

Với cách thứ nhất ta thường dùng đặt tên biến trong ngôn ngữ lập trình server (ví dụ java) còn cách thứ 2 ta thường dùng với database, hoặc html, css…

Trong dữ liệu json trả về thì kiểu snake case được đánh giá là dễ nhìn hơn:

// snake_case
{
    date_of_birth: "2017/12/01"
}
 
// camelCase
{
    dateOfBirth: "2017/12/01"
}

Tuy nhiên việc đọc dữ liệu json trả về thực hiện bởi phần mềm chứ anh em lập trình viên chúng ta chỉ đọc lúc test, debug thôi nên nó không ảnh hưởng nhiều lắm.

==> Tùy trường hợp, ví dụ trong code đang để camel case nhưng lúc hiển thị lại chuyển sang snake case thì sẽ rắc rối thêm.

2.4 Định dạng URI

Để chia tách các từ trong URI ta thường dùng dấu gạch ngang hoặc gạch dưới (áp dụng cho các các url cho các trang web)

Ví dụ  https://stackjava.com/web-service/restful-web-service.html ‎hoặc https://stackjava.com/web-service/restful_web_service.html

Không đặt thiểu kiểu camel case: https://stackjava.com/web-service/restfulWebService.html

2.5 Cấu trúc của URI

Việc đặt URI cho các api web service thường đặt theo kiểu cấu trúc thư mục, nhiều hành động chung 1 URI nhưng khác method:

Ví dụ:

  • GET /user: lấy thông tin tất cả user
  • GET /user/1: lấy thông tin của user có id = 1
  • POST /user: tạo user mới
  • PUT /user/1: cập nhật đối tượng user có id = 1
  • PATCH /user/1: cập nhật 1 thuộc tính cho đối tượng user có id = 1
  • DELETE /user/1: xóa đối tượng user có id = 1

Một số trường hợp phức tạp hơn:

  • GET /user/1/address: lấy thông tin address của đối tượng user có id = 1

nếu có thể lấy thông tin address 1 cách độc lập thì ta nên xây dụng 1 url riêng cho address: /address/{address_id}

Các bạn có thể chạy thử ví dụ trên http://petstore.swagger.io/#/ để xem cách thiết kế uri, method.

2.6 Bảo mật, xác thực trong restful web service

Request trong web service là stateless, nó cũng không sử dụng cookies nên ta không thể lưu thông tin đăng nhập vào session.

Để xác thực trong RESTful web service, sau khi đăng nhập client sẽ nhập được 1 token, mỗi lần gửi request sẽ gửi kèm token đó vào header của request. Server sẽ dựa vào token để xác thực client.

2.6 Sử dụng version cho các API

Khi muốn thay đổi kết quả trả về của các api, để không gây ảnh hưởng tới các ứng dụng đang sử dụng api cũ người ta chia thành các version khác nhau.

Ví dụ:

Bây giờ muốn lấy thông tin của tất cả đối tượng user nhưng thêm/bớt một số trường nhưng không cần phải sửa đổi api cũ, ta tạo 1 api mới

Việc tạo api theo version mới vừa đáp ứng được yêu cầu, lại không làm ảnh hưởng tới các ứng dụng đang dùng api cũ, nhưng thường các api cũ sẽ dần bị thay thế.

2.7 Status code trả về

Tương tự như việc sử dụng request method, khi trả về status ta nên chọn những status code thích hợp cho từng trường hợp:

Xem thêm về HTTP Status code: HTTP Status code là gì? Các loại HTTP Status code.

 

Giới thiệu về RESTful Web Service, xây dựng RESTful Web-Service

Okay, Done!

Phần tiếp theo mình sẽ xây dựng RESTful web service bằng Spring MVC để chúng ta có thể hiểu rõ hơn những lý thuyết ở trên:

Code ví dụ tạo RESTful Web Service với Spring MVC

Giới thiệu về RESTful Web Service, xây dựng RESTful Web-Service

 

References:

https://www.ibm.com/developerworks/library/ws-restful/index.html

https://en.wikipedia.org/wiki/Representational_state_transfer