Restapi version control strategy [eolink translation]

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 .