Versioning Strategy

It is critical that clients can count on services to be stable over time, and it's critical that services can add features and make changes.

#Requesting a version

The updatedge API uses query-string style explicit versioning to identify which version developers are calling with Major.Minor syntax (e.g 1.0).

Each API has it's own version which must be specified by appending an api-version parameter to the end of the request - this parameter is mandatory.

#Example

To find a user by specifying their email on the 1.0 version of the API, you would make a request to the following URL:

GET /users/findByEmail?email=someone@somewhere.com?api-version=1.0 HTTP/1.1
Copy

#Breaking Changes

Within a single version, any additions to the API will not constitute breaking changes but we may add new endpoints or addition properties to the responses of existing ones. Where either of these is the case, we will introduce a minor variation.

#Example

Request for Version 1.0

/users/findByEmail?email=someone@somewhere.com?api-version=1.0
Copy

Response

{
    "id": "d2b878c0-4b8b-464d-ab3e-d4d4e2837d61",
    "firstName": "Mary",
    "lastName": "Smith"
}
Copy

Request for Version 1.1

/users/findByEmail?email=someone@somewhere.com?api-version=1.1
Copy

Response

{
    "id":"d2b878c0-4b8b-464d-ab3e-d4d4e2837d61",
    "firstName":"Mary",
    "lastName":"Smith",           
    "LastShared": "2019-02-21T11:23:45.4242088Z}
}
Copy

#Breaking Changes

Breaking changes are any changes that require developer resources to maintain existing functionality. This includes resources used for investigation into the changes that need to be made, determination of features/endpoints being deprecated and final implementation of all these changes. A list of breaking changes are things like:

• Removing a param from the API request/response
• Modifying the name for any params or endpoints
• Change in the representation of values (eventid → userid)
• Change in behavior of endpoints.
• Adding/changing optional or required params (e.g., making name a required field in the request)
• Any breaking changes will be implemented as a step up in the major version number (.e.g 1.0 → 2.0)

#Deprecation

Deprecated versions or products will be unsupported and it is recommended that developers cease to use these APIs.

#Sunset

Once an API is sunset, the corresponding set of endpoints will no longer be accessible via the API. We will support requests to the current version and the previous version unless otherwise stated.