LF_APIStrat17_REST API Microversions
0 likes47 views
The document discusses versioning challenges for open source services deployed across multiple cloud platforms. It describes typical REST API versioning that works for single vendors but breaks down when different teams develop and deploy the software. The document introduces the concept of microversions to allow incremental feature updates while maintaining backwards compatibility. It also questions how to manage raising minimum versions and backwards compatibility over time.
![@sdague
Typical REST Versioning
Some time T1
GET /server/1
{
"server": {
"id": 1,
"name": "myserver",
"ips": ["10.42.100.1"]
}
}
Some time T2
GET /server/1
{
"server": {
"id": 1,
"name": "myserver",
"description": "….",
"ips": ["10.42.100.1"]
}
}
Generally accepted rules:
● clients should not break on additional keys
● adding new attributes is backwards compatible
● there is only ever going to be one version publicly accessable*
● the API will never roll back once in production (i.e. description can't just disappear once it's out there)
Generally accepted rules:
● clients should not break on additional keys
● adding new attributes is backwards compatible
● there is only ever going to be one version publicly accessable*
● the API will never roll back once in production (i.e. description can't just disappear once it's out there)](https://image.slidesharecdn.com/restapimicroversions-171109213836/85/LF_APIStrat17_REST-API-Microversions-2-320.jpg)
![@sdague
Typical REST Versioning
Some time T1
GET /server/1
{
"server": {
"id": 1,
"name": "myserver",
"ips": ["10.42.100.1"]
}
}
Some time T2
GET /server/1
{
"server": {
"id": 1,
"name": "myserver",
"description": "….",
"ips": ["10.42.100.1"]
}
}
Some time T3
GET /server/1
{
"server": {
"id": 1,
"name": "myserver",
"description": "….",
"tags": ["db", "ha"],
"ips": ["10.42.100.1"]
}
}
All works very well for single vendor services
● Github
● AWS
● Meetup
● etc](https://image.slidesharecdn.com/restapimicroversions-171109213836/85/LF_APIStrat17_REST-API-Microversions-3-320.jpg)
![@sdague
Typical REST Versioning
Some time T1
GET /server/1
{
"server": {
"id": 1,
"name": "myserver",
"ips": ["10.42.100.1"]
}
}
Some time T2
GET /server/1
{
"server": {
"id": 1,
"name": "myserver",
"description": "….",
"ips": ["10.42.100.1"]
}
}
Some time T3
GET /server/1
{
"server": {
"id": 1,
"name": "myserver",
"description": "….",
"tags": ["db", "ha"],
"ips": ["10.42.100.1"]
}
}
Development Workflow
push to prod push to prod push to prod](https://image.slidesharecdn.com/restapimicroversions-171109213836/85/LF_APIStrat17_REST-API-Microversions-4-320.jpg)
![@sdague
Client Experiencing A → B → C
Cloud C
GET /server/1
{
"server": {
"id": 1,
"name": "myserver",
"ips": ["10.42.100.1"]
}
}
Cloud A
GET /server/1
{
"server": {
"id": 1,
"name": "myserver",
"description": "….",
"ips": ["10.42.100.1"]
}
}
Cloud B
GET /server/1
{
"server": {
"id": 1,
"name": "myserver",
"description": "….",
"tags": ["db", "ha"],
"ips": ["10.42.100.1"]
}
}
Time's Arrow seems to go backwards.
Software is made to work on Cloud A, points at Cloud B still works, Cloud C is missing parameters
leading to possibly confusing late failures.](https://image.slidesharecdn.com/restapimicroversions-171109213836/85/LF_APIStrat17_REST-API-Microversions-8-320.jpg)
![@sdague
Client Experiencing A → B → C
Cloud C
GET /server/1
{
"server": {
"id": 1,
"name": "myserver",
"ips": ["10.42.100.1"]
}
}
Cloud A
GET /server/1
{
"server": {
"id": 1,
"name": "myserver",
"description": "….",
"ips": ["10.42.100.1"]
}
}
Cloud B
GET /server/1
{
"server": {
"id": 1,
"name": "myserver",
"description": "….",
"tags": ["db", "ha"],
"ips": ["10.42.100.1"]
}
}
Time's Arrow seems to go backwards.
Software is made to work on Cloud A, points at Cloud B still works, Cloud C is missing parameters
leading to possibly confusing late failures.
2.25 2.40 Base](https://image.slidesharecdn.com/restapimicroversions-171109213836/85/LF_APIStrat17_REST-API-Microversions-11-320.jpg)
![@sdague
Client Experiencing A → B → C
GET /server/1
{
"server": {
"id": 1,
"name": "myserver",
"ips": ["10.42.100.1"]
}
}
GET /server/1
{
"server": {
"id": 1,
"name": "myserver",
"ips": ["10.42.100.1"]
}
}
GET /server/1
{
"server": {
"id": 1,
"name": "myserver",
"ips": ["10.42.100.1"]
}
}
At time T3 with Microversions
Cloud A Cloud B Cloud C
GET /server/1
OpenStack-Version: compute 2.25
Status: 400
Version not found
GET /server/1
OpenStack-Version: compute 2.25
{
"server": {
"id": 1,
"name": "myserver",
"description": "great server",
"ips": ["10.42.100.1"]
}
}
GET /server/1
OpenStack-Version: compute 2.25
{
"server": {
"id": 1,
"name": "myserver",
"description": "great server",
"ips": ["10.42.100.1"]
}
}
Cloud A Cloud B Cloud C
Base
2.25](https://image.slidesharecdn.com/restapimicroversions-171109213836/85/LF_APIStrat17_REST-API-Microversions-12-320.jpg)
![@sdague
Questions for the Future
● Raising minimum versions?
● How much compat code do we need to
keep?
● Machine specifications?
OpenStack Nova Compute:
GET /
{
"versions": [
{
"id": "v2.0",
"links": [
{
"href": "http://openstack.example.com/v2/",
"rel": "self"
}
],
"status": "SUPPORTED",
"version": "",
"min_version": "",
},
{
"id": "v2.1",
"links": [
{
"href": "http://openstack.example.com/v2.1/",
"rel": "self"
}
],
"status": "CURRENT",
"version": "2.53",
"min_version": "2.1",
}
]
}](https://image.slidesharecdn.com/restapimicroversions-171109213836/85/LF_APIStrat17_REST-API-Microversions-14-320.jpg)
LF_APIStrat17_REST API Microversions
- 1. Versioning for Open Source services in Clouds Sean Dague - Open Source Developer Advocate @sdague [email protected] / [email protected] Nov 2nd 2017 REST API Microversions
- 2. @sdague Typical REST Versioning Some time T1 GET /server/1 { "server": { "id": 1, "name": "myserver", "ips": ["10.42.100.1"] } } Some time T2 GET /server/1 { "server": { "id": 1, "name": "myserver", "description": "….", "ips": ["10.42.100.1"] } } Generally accepted rules: ● clients should not break on additional keys ● adding new attributes is backwards compatible ● there is only ever going to be one version publicly accessable* ● the API will never roll back once in production (i.e. description can't just disappear once it's out there) Generally accepted rules: ● clients should not break on additional keys ● adding new attributes is backwards compatible ● there is only ever going to be one version publicly accessable* ● the API will never roll back once in production (i.e. description can't just disappear once it's out there)
- 3. @sdague Typical REST Versioning Some time T1 GET /server/1 { "server": { "id": 1, "name": "myserver", "ips": ["10.42.100.1"] } } Some time T2 GET /server/1 { "server": { "id": 1, "name": "myserver", "description": "….", "ips": ["10.42.100.1"] } } Some time T3 GET /server/1 { "server": { "id": 1, "name": "myserver", "description": "….", "tags": ["db", "ha"], "ips": ["10.42.100.1"] } } All works very well for single vendor services ● Github ● AWS ● Meetup ● etc
- 4. @sdague Typical REST Versioning Some time T1 GET /server/1 { "server": { "id": 1, "name": "myserver", "ips": ["10.42.100.1"] } } Some time T2 GET /server/1 { "server": { "id": 1, "name": "myserver", "description": "….", "ips": ["10.42.100.1"] } } Some time T3 GET /server/1 { "server": { "id": 1, "name": "myserver", "description": "….", "tags": ["db", "ha"], "ips": ["10.42.100.1"] } } Development Workflow push to prod push to prod push to prod
- 5. @sdague Upstream Versioning Upstream Development Workflow push to release push to release push to releasepush to releasepush to release PikeOcataNewtonMitakaLiberty
- 6. @sdague Liberty Mitaka Newton Liberty Mitaka Pike Upstream Code going into Clouds and Products PikeOcataNewtonMitakaLiberty Upstream Releases Cloud Product A Public Cloud B Public Cloud C
- 7. @sdague Liberty Mitaka Newton Liberty Mitaka Pike Client Perspective PikeOcataNewtonMitakaLiberty Upstream Releases Cloud Product A Public Cloud B Public Cloud C T1 T2 T3
- 8. @sdague Client Experiencing A → B → C Cloud C GET /server/1 { "server": { "id": 1, "name": "myserver", "ips": ["10.42.100.1"] } } Cloud A GET /server/1 { "server": { "id": 1, "name": "myserver", "description": "….", "ips": ["10.42.100.1"] } } Cloud B GET /server/1 { "server": { "id": 1, "name": "myserver", "description": "….", "tags": ["db", "ha"], "ips": ["10.42.100.1"] } } Time's Arrow seems to go backwards. Software is made to work on Cloud A, points at Cloud B still works, Cloud C is missing parameters leading to possibly confusing late failures.
- 9. @sdague The Assumed Good Enough Rules don't account for a Different Team Developing the Software than Deploying it
- 11. @sdague Client Experiencing A → B → C Cloud C GET /server/1 { "server": { "id": 1, "name": "myserver", "ips": ["10.42.100.1"] } } Cloud A GET /server/1 { "server": { "id": 1, "name": "myserver", "description": "….", "ips": ["10.42.100.1"] } } Cloud B GET /server/1 { "server": { "id": 1, "name": "myserver", "description": "….", "tags": ["db", "ha"], "ips": ["10.42.100.1"] } } Time's Arrow seems to go backwards. Software is made to work on Cloud A, points at Cloud B still works, Cloud C is missing parameters leading to possibly confusing late failures. 2.25 2.40 Base
- 12. @sdague Client Experiencing A → B → C GET /server/1 { "server": { "id": 1, "name": "myserver", "ips": ["10.42.100.1"] } } GET /server/1 { "server": { "id": 1, "name": "myserver", "ips": ["10.42.100.1"] } } GET /server/1 { "server": { "id": 1, "name": "myserver", "ips": ["10.42.100.1"] } } At time T3 with Microversions Cloud A Cloud B Cloud C GET /server/1 OpenStack-Version: compute 2.25 Status: 400 Version not found GET /server/1 OpenStack-Version: compute 2.25 { "server": { "id": 1, "name": "myserver", "description": "great server", "ips": ["10.42.100.1"] } } GET /server/1 OpenStack-Version: compute 2.25 { "server": { "id": 1, "name": "myserver", "description": "great server", "ips": ["10.42.100.1"] } } Cloud A Cloud B Cloud C Base 2.25
- 13. @sdague REST API Microversions ● Concept – Inspired by HTTP Content negotiation – Allow incremental feature roll out in API instead of waiting for major version bump – Introduced in 2014 in OpenStack Nova / Ironic (expanded to 6 projects now) ● Technical Details – Discoverable in root version document – An explicit version header on each request – Global incrementing version for entire service – Defaults to minimum value – Services continue to support old versions – Hard 400 fail if version not found ● Blog writeup including personas - https://dague.net/api-mv Very long history of getting here available at bar later upon request
- 14. @sdague Questions for the Future ● Raising minimum versions? ● How much compat code do we need to keep? ● Machine specifications? OpenStack Nova Compute: GET / { "versions": [ { "id": "v2.0", "links": [ { "href": "http://openstack.example.com/v2/", "rel": "self" } ], "status": "SUPPORTED", "version": "", "min_version": "", }, { "id": "v2.1", "links": [ { "href": "http://openstack.example.com/v2.1/", "rel": "self" } ], "status": "CURRENT", "version": "2.53", "min_version": "2.1", } ] }
- 16. @sdague OpenStack APIs vs OpenAPI ● Many OpenStack APIs evolved around WADL ● Attempt to retrofit OpenAPI definitions in 2015 to many core APIs, 2 key issues – Duplicate actions that don't map to Swagger/OpenAPI ● POST /servers/{id}/action {"reboot": ""} ● POST /servers/{id}/action {"resize": {"flavor": "m1.large"}} – Micro versions also don't really fit ● Could they?
- 17. @sdague Parting Thoughts ● There are specific challenges to Open Source network consumable services being deployed in multiple organizationally controlled clouds – Tooling today largely doesn't consider that ● If we don't consider it, we make it harder to do non single vendor Open Source all the way to the edge – How do we prevent that? THANKS! Sean Dague dague.net [email protected] / [email protected] https://dague.net/api-mv