Versioning best practices

Microsoft recommends the following versioning best practices for Azure Storage:

  • Explicitly specify the REST protocol version to use for every request.

  • Set a default version for Azure Blob Storage by using the Set Blob Service Properties operation. The default version specifies the version to use for anonymous requests for which the version header can't be set.

  • Client software that uses a shared access signature (SAS) URL to access storage resources might experience unexpected behavior when the SAS URL specifies a storage service version that's newer than the version that's used by the client software. To ensure that your clients work well with SAS tokens, we recommend the following approaches:

    • For version 2014-02-14 and later: If you're a SAS token consumer who's using the REST API, you can override the REST protocol version to specify the appropriate version by using the api-version parameter. For more information, see Versioning for Azure Storage.

      If you're a SAS token consumer who's using the Azure Storage client library, the library ensures that the correct REST protocol version is requested.

    • For version 2013-08-15 and earlier: Code that prepares and distributes shared access signature URLs (that is, SAS providers or generators) should specify versions that are understood by the client software (that is, SAS consumers) that's making storage service requests.

  • Always use the latest Azure Storage version to benefit from optimizations that are included with each new version. Some examples of such changes include:

    • Version 2013-08-15 introduced the JSON payload format that reduces network bandwidth usage by up to 70 percent compared to the OData AtomPub protocol.

    • Version 2013-08-15 allows SAS providers and generators to add certain response headers, such as cache-control, content-disposition, and content-type via SAS query parameters.

    • Version 2011-08-18 introduced the quoted ETag and Accept-Ranges response headers that are required for optimized download and streaming via browsers.

See also

Versioning for Azure Storage