Create examples of api versioning

[mvogelgesang]

It would be helpful for consumers of these standards to have documented examples of api versioning. For example, what is considered a minor change, major change, etc.

Good examples of this are provided by Karl Fogel in Producing Open Source Software: How to Run a Successful Free Software Project

GET Request Examples

https://exampleapi.gov/person

New Version Number (Major Change Criteria)

• the output for a given response changes its overall organization.

Old

{
    'name': 'Jane',
    'phone': '555-5555'
}

New

{
    'name': 'Jane',
    'phoneNumbers': {
        'home': '555-5555',
        'work': '333-9999'
    }
}

Minor version, no new version number needed

• New fields may be present but the construction of existing objects/arrays does not change

Old

{
    'name': 'Jane',
    'phone': '555-5555'
}

New

{
    'name': 'Jane',
    'phone': '555-5555',
    'zipCode': '12345'
}

POST Request Examples

Major changes

• Existing validation rules change, new fields or formats are required

Minor version changes

• Updating error messages (text output rather than error codes)
• Adding new fields to the output, not changing the structure

[Ryandaydev]

Good idea, Mark. I have also heard the term "breaking changes" used in regard to major changes. So consumers can trust that until the version changes, they are not required to re-code or re-deploy.

[Ryandaydev]

For SOAP/XML web services, this document has some good guidance:

Best practices for Web services versioning

Highlights:

Backwards Compatible Changes

• Addition of new WSDL operations to an existing WSDL document.
• Addition of new XML schema types within a WSDL document that are not contained within previously existing types

Non Backwards Compatible Changes

• Removing an operation
• Renaming an operation
• Changing the parameters (in data type or order) of an operation
• Changing the structure of a complex data type.