REST API Versioning

Hiện nay mô hình API – Client đang ngày càng phổ biến trong việc xây dựng các Web App và đặc biệt là với việc xây dựng các Mobile App thì việc xây dựng API là điều gần như không thể thiếu. Với việc API được sử dụng nhiều như vậy đồng nghĩa với việc người ta phải tạo ra một chuẩn chung trong việc thiết kế API. Và thế là REST ra đời.

Hiểu một cách đơn giản thì REST là một kiểu thiết kế API, nó là tập hợp những quy định và nguyên tắc thiết kế dành cho các Web Service (cung cấp API).

Tuy nhiên, khi đã là một Web Service tức là tất cả chúng ta đã xác lập rằng sẽ phải phân phối những API cho Client để sử dụng đúng không nhỉ. Nếu không phân phối ra bên ngoài thì việc thiết kế xây dựng Web Service không có công dụng gì cả. Tất nhiên rồi =)) Chính cho nên vì thế mà việc cần chăm sóc đó là không làm ảnh hướng đến những Client đang sử dụng API của tất cả chúng ta .

Lưu ý: REST không quy định quy chuẩn nào cho việc đánh version API. Dưới đây là cách mà mình thấy nó phù hợp và cũng được sử dụng phổ biến nhất.

Đánh version cho REST API

Versioning an interface is just a “ polite ” way to kill deployed clients .Roy Fielding.

Có một vấn đề trong việc xây dựng API đó là đánh version. Hiện nay đa phần người ta sử dụng nguyên tắc Semantic Versioning để đánh version cho các ứng dụng, thư viện, framework,… Tuy nhiên chúng ta có nên áp dụng nó cho API?

Bạn hoàn toàn có thể đọc thêm về Semantic Versioning trải qua bài viết của một nguời anh mình : https://viblo.asia/p/semantic-versioning-OeVKBN2EKkW

MAJOR.MINOR.PATCH

• 

Tuy nhiên với API thì nó sống sót một yếu tố đó là chỉ cần Web Service có một đổi khác nhỏ thôi thì sẽ phải update version và nó sẽ khiến cho tổng thể Client phải update lại source code cho App của họ hay tối thiểu là update lại biến thiên nhiên và môi trường. Và thực sự nó là một điều không một ai muốn cả, không ai hoàn toàn có thể theo sát từng update nhỏ nhất của Service và update cho App của mình cả .
Khi thiết kế xây dựng Web Service và release thì tất cả chúng ta vẫn đánh version dạng Semantic tuy nhiên nó chỉ dùng trong internal thôi. Còn với bên ngoài tất cả chúng ta chỉ sử dụng phần Major để đưa cho Client, còn phần Minor và Patch chúng sẽ bị “ tàng hình ” :))
Ví dụ như Web Service có version là 1.2.3 thì tất cả chúng ta chỉ cho Client biết là API dùng version 1. Như vậy thì với những update nhỏ tất cả chúng ta sẽ không cần phải thông tin cho Client để update app của họ. Chỉ khi Web Service có một Breaking Change và phải biến hóa Major thì Client mới cần update app của họ .

Breaking Change?

Hiểu đơn thuần là khi có Breaking Change tức là API bị biến hóa và Client bắt buộc phải update lại app nếu không muốn bị lỗi. Những sự biến hóa đó hoàn toàn có thể là :

Đổi format response: từ XML -> JSON chẳng hạn

Đổi cấu trúc response trả về.

Ví dụ như đổi property name từ:

{
    "name": "Tien Nguyen"
}

Sang thành :

{
    "displayName": "Tien Nguyen"
}

Hay là đổi cấu trúc sang thành :

{
    "data": {
        "displayName": "Tien Nguyen"
    }
}

Cách đánh version thì có rồi, còn giờ là việc đưa version vào sử dụng cho phía Client. Có 4 cách thông dụng nhất như sau .

Đánh version thông qua URI

Trong URI thì có 2 cách như dưới đây .

URL Path

http://www.example.com/api/1/products
http://www.example.com/api/v1/products
http://apiv1.example.com/api/products

Khi nhìn vào đây chắc hẳn các bạn sẽ thấy quen đúng không. Theo mình thấy thì cách này là cách đang được sử dụng rộng rãi và phổ biến nhất. Version sẽ được gắn trực tiếp vào trong URI của API. Như 3 cách ở trên cũng là ví dụ thôi, có thể có nhiều kiểu tùy theo nguyên tắc của team nữa. Ví dụ có thể là /api-version-1/ hay v1.example.com chẳng hạn.

Query Parameter

http://www.example.com/api/products?version=1

Cách này thì mình thấy hầu hết không có mấy ai sử dụng cả. Vì có sống sót khá là nhiều yếu tố trong việc routing phía server cũng như việc gọi API phía Client. Đặc biệt nhìn nó không ngầu tẹo nào. :))

Đánh version thông qua Header

Với cách sử dụng Header này thì nhìn chung URL của API trông sẽ khá là thật sạch, ngăn nắp. Tuy nhiên cách này lại có 1 vài điểm yếu kém so với dùng URI đó là sẽ khó cho clear version hơn, khó test hơn, …

Custom Header

Cách này có nghĩa là bạn sẽ tự tạo ra 1 header riêng để nhận ra version khi Client request lên phía server. Ví dụ như :

Accepts-version: 1
Accept-version: 1
Version: 1
Phien-ban: 1

Accept header

Accept là một header quy định của HTTP. Các bạn có thể xem thêm ở đây:

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept
Về cơ bản là những bạn sẽ thêm version trong value của nó kiểu :

Accept: application/json;version=1

Túm váy lại

• REST không có quy chuẩn cụ thể cho việc đánh version API.
• Sử dụng Semantic Versioning khá khó trong việc triển khai version cho API.
• Có 2 cách để version đó là qua URI và Header.
• Và quan trọng nhất: Hãy luôn làm tốt phần API doc và đặc biệt là cả change log.

Tham khảo :

Source: https://www.lesabeilles.biz
Category: Mạng Internet