Web Services Versioning
The versioning protocol adopted by the GAGE Facility (GAGE) applies to each individual web service. An individual web service is identified by the hostname, always web-services.unavco.org, and the path which is that part of the URL between the hostname and the "?". That part of the URL that follows the "?" are known as the query parameters.
Currently, each GAGE web service has a version that is identified by the trailing node of the URL path. For example, in the URL, http://web-services.unavco.org/met/data/P005/beta?starttime=2012-05-01T00:00:00&endtime=2012-05-02T02:59:59&tsFormat=iso8601 the version is "beta". Versions will either be "beta" releases or the letter "v" followed by an integer for specific production releases. Services identified as "beta" are subject to change "in place" without notification.
The following points describe what kinds of changes result in an updated version.
- A URL path is never really changed; if such a modification is required, the original service will be deprecated and a new one created with a version identifier of "beta" or "v1".
- A change to the internal process of an existing web service will not result in an updated version.
- A change to the output produced by an existing web service will result in an updated version.
- The addition of a new, optional, query parameter will not result in a new version and the default value of the query parameter will be set so that the web service will behave as previously if the new parameter is not specified.
- The addition of a new, required parameter will result in an updated version.
Deprecated services will eventually be removed from the documentation, but will remain available for a period of time to be determined to allow users time to migrate to the current versions. When the time period expires the old version will be removed and be inaccessible.
Last modified: 2023-05-18 14:37:27 America/Denver