Microservices , It is a popular trend to develop and build cloud native applications at this stage .API Version control helps speed up iterative updates when identifying needed adjustments .
According to one of the key components of the microservice architecture , yes API Design and specification of . in the light of API, Version control is indispensable , It enables enterprise customers to continuously use what they have at this stage RESTAPI , And when they are fully prepared, move their applications to a new API .
When to update the new version ？
Version control helps us in API Enable interrupt changes in , For example, the adjustment of the application format according to the import mandatory parameters 、 The format adjustment or structure optimization of the response message adjusts the implementation of the response data , Or incompatible use API To strengthen the role of supply .
What's wrong RESTAPI Version control
Yes 5 There are different ways to do .
according to URI Relative path realizes version control
Realize version control according to the viewing parameters
According to custom header Achieve version control
Implement version control according to the content discussion
according to API Management tools realize version control
Version according to URI route
Is one of the most common ways to implement version control for endpoints . Versions need not be all numbers , or v[x] Format , You can use other meaningful identifiers , Such as data or version number , It's good for API The production team seamlessly merges a new adjustment .
http://api.example.com/v1
Realize version control according to the viewing parameters
Another option is to use version as the viewing parameter , This method is simple and easy to implement , In addition to establishing the prescribed version , Otherwise we can bring the latest API Set the version to the initial version .
Such as ：
http://api.example.com/customers?version=v1
According to custom header Achieve version control
We can also implement version control according to the custom header . This is beneficial to prevent URI Realize other filling .
@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();
}
}
The only major drawback of such an approach is that it maintains a header To use header Version and processing .
Implement version control according to the content discussion
This method can help enterprise customers use AcceptHeader Specifically apply for 1 A version . If the client does not apply for the corresponding version , Then the service can be realized to supply the initial representation .
GET /customers/1234 HTTP/1.1 Accept ：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();
}
}
In this way , We will start to include Accept The head of the newspaper 2 Versions GET/productsendpoint . When using header It's worth it v1 issue curl application , The response will be based on version v1 .
curl -L -X GET 'http://localhost:8080/products' \ -H 'Accept: application/vnd.v1+json'
[
{
"name": "IdeaPad Slim 5 (15, AMD)"
}
]
When using header It's worth it v2 issue curl application , The response will be based on v2 edition .
curl -L -X GET 'http://localhost:8080/products' \
-H 'Accept: application/vnd.v2+json'
[
{
"name": "IdeaPad Slim 5 (15, AMD)"
}
]
When not successfully sent Accept At the beginning , It will respond to the default version , It's here v1 edition .
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"
}
With the help of API Management tools realize version control
There are many in the market nowadays API Management tools , It can realize data visualization and version control , The procedure flow is relatively simple , image Eolink：www.eolink.com , Due to the function of automatic backup of change history , Just build the version number , Bind the version number of different change history , Version control can be achieved , API After modification, it will be automatically synchronized to the interface document of the corresponding version .
summary
With API Drive the rapid development of architecture and more and more people use , The most important thing is to API Achieve version control , To minimize API The impact of changes and better backward compatibility . Each version control technology mentioned above has its own advantages and disadvantages , So I strongly recommend API Management tools Eolink .
