2. 2CONFIDENTIAL
AGENDA
Why do we need Versioning1
Different schemas for Versioning2
Specifics of Versioning for Services3
Example of Service API Versioning used for Zero-Down-Time Deployment4
3. 3CONFIDENTIAL
Why do we need Versioning
Software versioning is the process of assigning either unique version
names or unique version numbers to unique states of computer
software, mostly used for compatibility. [wiki]
https://en.wikipedia.org/wiki/Software_versioning
Examples of Versioning Schemas:
- Semver
- Maven Versioning Numbers
- Debian Versioning Policy
- Microsoft Assembly Versioning
Service Versioning is subset of Software Versioning, can be compares with
Library versioning
Software Versioning is often used to indicate degree
of compatibility
4. 4CONFIDENTIAL
SEMVER Explained
https://semver.org/
Semantic Versioning , proposed by Tom Preston-Werner, inventor of Gravatars, is
a formal convention for specifying compatibility using a three-part version
number: major version; minor version; and patch.
Format: <major>.<minor>.<patch>
<major> - when you make incompatible API changes,
<minor> - when you add functionality in a backwards-compatible manner
<patch> - when you make backwards-compatible bug fixes.
Examples: 2.1.4
3.5.1
3.5.2
5. 5CONFIDENTIAL
Maven Version Numbers Explained
https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm
Maven Version Number – versioning schema used by maven to
simplify your dependency management workload.
Maven 3 Example:
https://maven.apache.org/docs/history.html
3.5-SNAPSHOT
3.5.0-beta-1
3.5.1
Format:
<major>.<minor>.<incremental>([ -<qualififer> ] | [ -<build> ])
6. 6CONFIDENTIAL
Microsoft Assembly Versioning
Maven Assembly Versioning – used by .NET CLR to manage
dependencies between assemblies
https://docs.microsoft.com/en-us/dotnet/framework/app-domains/assembly-versioning
Format:
<major version>.<minor version>.<build number>.<revision>
Example: 1.5.1254.0
7. 7CONFIDENTIAL
Versioning and API
Components interacts with each other through interfaces1
Version of API and Version of Implementation is not the same2
Compatibility is dependent on API3
API Type Examples:
API Library
Network API
Application Binary Interface
etc
Examples:
API is Implementation: Struts, Guava
API is not Implementation: Servlet API
8. 8CONFIDENTIAL
Services and Libraries Comparison
Provides functionalities for use/reuse1
Provides access through API2
Compatibility is important3
Similarities
Library embedded by client,
While Service is Deployed by providers.
1
Library client can embed multiple
versions of the same library.
Example: OSGI, JIGSAW
3
Differences
Service Consumer can’t ignore
changes made by provider
2
Service Provide can expose multiple
versions of API on the same service.
4
9. 9CONFIDENTIAL
Service Versioning Practices
Service Binary Versioning and Service API Version is not the same.1
Same service can provides multiple API of different versions2
Support of multiple major API versions can be used to get backward
compatibility.
3
Consider forward compatibility on consumer side, as well as backward
compatibility on provider side.
4
Semver is useful for Service API Versioning5
Minor version doesn’t make any sense for Service API.6
10. 10CONFIDENTIAL
Example of REST API Versioning Approaches
Using HTTP Header:
Request HTTP Header:
Accept: application/vnd.acme.*-v1+json
Response HTTP Header:
Content-Type: application/vnd.acme.customer-v1+json
Unsupported Version Error :
415 HTTP status code for an unsupported version request
Using URL:
http://example.org/service/v1/actors/1
RestfulPragmatic
http://www.lexicalscope.com/blog/2012/03/12/how-are-rest-apis-versioned/
11. 11CONFIDENTIAL
Example of Service API versioning for Echo ZDT
ServiceServiceService ASG
REST V1
BUSINESS CODE
ServiceServiceService ASG
REST V2REST V1
BUSINESS CODE
*ASG – auto scaling group
CONSUMER OF SERVICE CONSUMER OF SERVICE
DATABASE
LOAD BALANCER
LOAD BALANCER
REST-APIV1
Calls
REST Calls
are Disabled
REST V1
REST V2
REST-APIV2
Calls
NewVersionof
Service
BaselineVersionof
Service
REST Calls
are Disabled
REST Calls
are Enabled
NewVersionof
Consumer
BaselineVersionof
Consumer
Red are Rest API calls, which are enabled on Load-Balancer side
Black are Rest API calls, which are disabled on Load-Balancer side
Green are REST API calls of Version 2
Blue are REST API calls of Version 1
Dashed are channels, which either could be enabled or disabled channels, but assumed to be not
used
Two version of service deployed during
ZDT transition phase.
1
Multiple versions of API is used to get
backward compatibility.
3
APIs not compatible – used different major
versions
4
Old service support only API version, while
new two versions of API.
2
PoC to assess ZDT:
12. 12CONFIDENTIAL
Sequence Diagram of Echo ZDT Example
Spring MVC
@RestController
EchoResourceV1ImplUser
Spring MVC
@RestController
EchoResourceV2Impl
@Service
EchoService
Request via depracted URL V1 invoke doBusiness()
returns Business Entity
Return EchoDTO in JSON format
uses depracted properties
Request via URL V2 invoke doBusiness()
returns Business Entity
Return EchoDTO in JSON format
uses new properties
EchoDTO
@Depracated
-oldPayloadProperty
-newPayloadProperty
Samemethodwithsame
argumentlistisinvoked
SemVer
Examples where Versionings is required:
Hadrware: wireless, wirefull
Software: Application, Libraries, Networks,
API/ABI
Who introduced SEMVER?
Who introduced SEMVER?
Who introduced SEMVER?
Method Signatur is interface
Library API example – Servlet API
Service API – implementation can be java or node, API the same.
In terms of versioning services and libraries have lots of similarities.
SOAP another example of Service API
Message Queue also another example of API
Zero-Down-Time Deployment what is.
Simple Echo service implemented to demonstrate Zero-Downtime capabilities to deploy service with breaking changes in API.
