RESTAPI 版本控制政策【eolink 翻譯】

微服務，是現階段開發建設雲原生應用程式的流行趨向。API 版本控制有益于在辨識出所需要的調節時加速疊代更新的速度。

根據微服務架構的關鍵構件其一，是 API 的設計和規範。針對 API，版本控制是不可或缺的，它能使企業客戶能不斷運用現階段有的 RESTAPI ，并在他們做好充分的準備時将他們的應用程式轉移到一個新的 API 。

何時要更新新版本？

版本控制幫我們在 API 中啟用中斷的變化，譬如根據導進強制參數對申請格式實作的調節、響應消息的格式調節或結構優化對響應資料實作的調節，或是不相容使用 API 來供應加強的作用。

怎麼對RESTAPI進行版本控制

有5種不同的方法能做到。

• 根據URI相對路徑實作版本控制
• 根據檢視參數實作版本控制
• 根據自定義header實作版本控制
• 根據内容讨論實作版本控制
• 根據API管理工具實作版本控制

版本根據URI路徑

是為端點實作版本控制的最常見的方法其一。版本無須都是數字，或是 v[x] 格式，您可以用其他的有意義的辨別符，如資料或版本号，這有益于 API 生産團隊無縫地合并一個新的調節。

http://api.example.com/v1
           

根據檢視參數實作版本控制

另外一種選擇是運用版本當做檢視參數，這樣的方法簡單容易實作，除了确立規定的版本，不然我們能夠将最新的 API 版本設定成初始版本。

如：

http://api.example.com/customers?version=v1
           

根據自定義 header 實作版本控制

我們還能根據自定義表頭實作版本控制。這有益于防止對 URI 實作其他的填充。

@RestController

@RequestMapping("/")

public class ProductController {

@Autowired
 private ProductRepository repository;

@GetMapping(value= "products", headers = {"X-API-VERSION=v1"})
public List<Product> findAll() {
       return repository.findAll();
 }

 @GetMapping(value= "products", headers = {"X-API-VERSION=v1"})
 public List<Product> findAllV2() {
       return repository.findAll();
 }
}
           

這樣的方法的僅有的主要缺點是它要維護一個 header 以運用 header 的版本和處理。

根據内容讨論實作版本控制

這樣的方法能協助企業客戶運用 AcceptHeader 專門申請1個版本。倘若用戶端不申請相應版本，則能實作服務以供應初始表示。

GET /customers/1234 HTTP/1.1 接受：application/vnd.v1+json
	@RestController
@RequestMapping("/")
public class ProductController {


 @Autowired
 private ProductRepository repository;

    // Find
    @GetMapping(value= "products", headers = {"Accept=application/vnd.v1+json"})
    List<Product> findAll() {
        return repository.findAll();
    }

    @GetMapping(value= "products", headers = {"Accept=application/vnd.v2+json"})
    List<Product> findAllV2() {
        return repository.findAll();
    }
   
 }
           

如此一來，我們就開啟了包含 Accept 報頭的2個版本的 GET/productsendpoint 。當運用 header 值的 v1發出 curl 申請時，響應将根據版本 v1 。

curl -L -X GET 'http://localhost:8080/products' \ -H 'Accept: application/vnd.v1+json'
           

[    

{      

 "name": "IdeaPad Slim 5 (15, AMD)"  

  } 

]

當運用 header 值的 v2 發出 curl 申請時，響應将根據 v2 版本。

curl -L -X GET 'http://localhost:8080/products' \
-H 'Accept: application/vnd.v2+json'

[
{
    "name": "IdeaPad Slim 5 (15, AMD)"
 }
]
           

當未成功發送 Accept 報頭時，它将響應預設版本，就是這裡的 v1 版本。

curl -L -X GET 'http://localhost:8080/products' 
[    
{       
    "name": "IdeaPad Slim 5 (15, AMD)"  
} 
] 
	406 Not Acceptable
curl -L -X GET 'http://localhost:8080/products' 
-H 'Accept: application/vnd.v3+json'

{
"timestamp": "2021-09-13T14:30:12.263+0000",
"status": 406,
"error": "Not Acceptable",
"message": "Could not find acceptable representation",
"path": "/products"
}
           

借助 API 管理工具實作版本控制

如今市場上有許多API管理工具，能做到資料可視化實作版本控制，程式流程還都較為簡單，像 Eolink：www.eolink.com ， 由于有自動備份更改曆史的功能，隻要建構版本号，給不一樣的更改曆史綁定版本号，就能做到版本控制， API 修改後還會自動同步到相比對版本的接口文檔裡。

總結

伴随着 API 驅動架構的飛速發展和越來越多的人使用，最重要的是對 API 實作版本控制，以最大程度地降低 API 更改所産生的影響并具備更佳的向後相容性。以上所述每一種版本控制技術都各有利弊，是以我還是強烈推薦用 API 管理工具 Eolink 。