Step by step evolution of restful API version Frankel

Design an intuitive 、 User friendly RESTful API It's a hard job . If this is your first attempt , This may already be a difficult task . planning API Life cycle management may be an afterthought . But it is possible anyway ： In this article , I want to propose a serious way to develop your API, Even if it has no plans .

 

Let's assume that one says “Hello” The sample application for ：

> curl http://org.apisix/hello Hello world > curl http://org.apisix/hello/Joe Hello Joe

 

Use API gateway

The first and most critical step is to stop exposing applications directly to the Internet , And build a API gateway .

 

Versioning API

evolution API signify API Multiple versions of need to coexist at some point .

Three methods ：

curl http://org.apisix/hello?version=1 curl http://org.apisix/hello?version=2   curl -H 'Version: 1' http://org.apisix/hello curl -H 'Version: 2' http://org.apisix/hello   curl http://org.apisix/v1/hello curl http://org.apisix/v2/hello

At this stage , We have configured two routes , One is versioned , The other is non versioned ：

> curl http://org.apisix/hello  Hello world  > curl http://org.apisix/v1/hello  Hello world

 

Migrate users from non versioned paths to versioned paths

We're right API Version control is in place , But our users may still be using old non versioning API. We want them to move , But we can't just delete old routes , Because our users don't know it . Fortunately, ,301 HTTP The status code is our friend ： We can let users know that the resources have changed from http://org.apisix/hello Moved to http://org.apisix/v1/hello. It needs to be configured on the initial route Redirection plug-ins ：

curl http://apisix:9080/apisix/admin/routes/1 -H 'X-API-KEY: xyz' -X PATCH -d ' {   "plugins": {     "redirect": {       "uri": "/v1$uri",       "ret_code": 301     }   } }'

It turns out to be interesting :

Either the user will use the new endpoint transparently , Because they will follow , Or their integration is interrupted , They will notice 301 Status and new to use API Location .

 

Know your users

You may have noticed , up to now , We don't know who is using our API. When we have to introduce change , We have to be creative , Do not destroy the user's use . Other changes may not be so easy to deal with . therefore , We should try to understand our users , In order to contact them if necessary .

 

Create user

You should probably start seeing your users visit the registration page , Depending on how much you limit unauthenticated usage . There are many ways to register ; There may be ：

• Automate or require as many manual verification steps as possible
• Free or paid
• It's as simple as asking for an email without further verification , Or as complex as needing more data
• wait .

It depends on your situation .

 

Production testing

At this stage , We are now ready to let users know about our Hello world API Improved version . I assume that our team has thoroughly tested it , But new code is always risky . Deploying a flawed new version of an existing application may be beneficial to API The image of the provider （ And income ！） Have a negative impact .

 

Discard old version

Most users may migrate to the new version to benefit from it , But a small part of it will remain v1.1 On . There may be several reasons for this ： There is no suitable time （ Tips ： It will never ）、 Too expensive 、 There is not enough migration power , wait . But as a API Provider , Each deployed version has a cost . You may need to deactivate... At some point v1.

 

Conclusion

In this article , We described a simple step-by-step process to manage API Life cycle of ：

1. Don't expose your API; Set one in front API gateway
2. Use path 、 Query parameter or request header pair existing API Version control
3. Migrate users from an unversioned endpoint to one with 301 Versioned endpoint of state code
4. Gently push your user to register
5. Test in production , First, copy the traffic , Then transfer a small number of users to the new version
6. Official release of new version
7. Deprecation of older versions is communicated through standard response headers

Click on the title for details

The complete source code of this article can be found in Github In order to maven Format found .

API Version control related articles ：

• https://stripe.com/blog/api-versioning
• https://apisyouwonthate.com/blog/api-evolution-for-rest-http-apis
• https://apigility.org/documentation/api-primer/versioning