<p>API versioning allows you to alter behavior between different clients. REST framework provides for a number of different versioning schemes.</p>
<p>Versioning is determined by the incoming client request, and may either be based on the request URL, or based on the request headers.</p>
<p>There are a number of valid approaches to approaching versioning. <ahref="http://www.infoq.com/articles/roy-fielding-on-versioning">Non-versioned systems can also be appropriate</a>, particularly if you're engineering for very long-term systems with multiple clients outside of your control.</p>
<h2id="versioning-with-rest-framework">Versioning with REST framework</h2>
<p>When API versioning is enabled, the <code>request.version</code> attribute will contain a string that corresponds to the version requested in the incoming client request.</p>
<p>By default, versioning is not enabled, and <code>request.version</code> will always return <code>None</code>.</p>
<h4id="varying-behavior-based-on-the-version">Varying behavior based on the version</h4>
<p>How you vary the API behavior is up to you, but one example you might typically want is to switch to a different serialization style in a newer version. For example:</p>
<pre><code>def get_serializer_class(self):
if self.request.version == 'v1':
return AccountSerializerVersion1
return AccountSerializer
</code></pre>
<h4id="reversing-urls-for-versioned-apis">Reversing URLs for versioned APIs</h4>
<p>The <code>reverse</code> function included by REST framework ties in with the versioning scheme. You need to make sure to include the current <code>request</code> as a keyword argument, like so.</p>
<p>The above function will apply any URL transformations appropriate to the request version. For example:</p>
<ul>
<li>If <code>NamespacedVersioning</code> was being used, and the API version was 'v1', then the URL lookup used would be <code>'v1:bookings-list'</code>, which might resolve to a URL like <code>http://example.org/v1/bookings/</code>.</li>
<li>If <code>QueryParameterVersioning</code> was being used, and the API version was <code>1.0</code>, then the returned URL might be something like <code>http://example.org/bookings/?version=1.0</code></li>
</ul>
<h4id="versioned-apis-and-hyperlinked-serializers">Versioned APIs and hyperlinked serializers</h4>
<p>When using hyperlinked serialization styles together with a URL based versioning scheme make sure to include the request as context to the serializer.</p>
<p>Unless it is explicitly set, the value for <code>DEFAULT_VERSIONING_CLASS</code> will be <code>None</code>. In this case the <code>request.version</code> attribute will always return <code>None</code>.</p>
<p>You can also set the versioning scheme on an individual view. Typically you won't need to do this, as it makes more sense to have a single versioning scheme used globally. If you do need to do so, use the <code>versioning_class</code> attribute.</p>
<p>The following settings keys are also used to control versioning:</p>
<ul>
<li><code>DEFAULT_VERSION</code>. The value that should be used for <code>request.version</code> when no versioning information is present. Defaults to <code>None</code>.</li>
<li><code>ALLOWED_VERSIONS</code>. If set, this value will restrict the set of versions that may be returned by the versioning scheme, and will raise an error if the provided version if not in this set. Defaults to <code>None</code>.</li>
<li><code>VERSION_PARAMETER</code>. The string that should used for any versioning parameters, such as in the media type or URL query parameters. Defaults to <code>'version'</code>.</li>
<p>This scheme requires the client to specify the version as part of the media type in the <code>Accept</code> header. The version is included as a media type parameter, that supplements the main media type.</p>
<p>Here's an example HTTP request using the accept header versioning style.</p>
<pre><code>GET /bookings/ HTTP/1.1
Host: example.com
Accept: application/json; version=1.0
</code></pre>
<p>In the example request above <code>request.version</code> attribute would return the string <code>'1.0'</code>.</p>
<p>Versioning based on accept headers is <ahref="http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http#i_want_my_api_to_be_versioned">generally considered</a> as <ahref="https://github.com/interagent/http-api-design#version-with-accepts-header">best practice</a>, although other styles may be suitable depending on your client requirements.</p>
<h4id="using-accept-headers-with-vendor-media-types">Using accept headers with vendor media types</h4>
<p>Strictly speaking the <code>json</code> media type is not specified as <ahref="http://tools.ietf.org/html/rfc4627#section-6">including additional parameters</a>. If you are building a well-specified public API you might consider using a <ahref="http://en.wikipedia.org/wiki/Internet_media_type#Vendor_tree">vendor media type</a>. To do so, configure your renderers to use a JSON based renderer with a custom media type:</p>
<p>This scheme requires the client to specify the version as part of the URL path.</p>
<pre><code>GET /v1/bookings/ HTTP/1.1
Host: example.com
Accept: application/json
</code></pre>
<p>Your URL conf must include a pattern that matches the version with a <code>'version'</code> keyword argument, so that this information is available to the versioning scheme.</p>
<p>To the client, this scheme is the same as <code>URLParameterVersioning</code>. The only difference is how it is configured in your Django application, as it uses URL namespacing, instead of URL keyword arguments.</p>
<pre><code>GET /v1/something/ HTTP/1.1
Host: example.com
Accept: application/json
</code></pre>
<p>With this scheme the <code>request.version</code> attribute is determined based on the <code>namespace</code> that matches the incoming request path.</p>
<p>In the following example we're giving a set of views two different possible URL prefixes, each under a different namespace:</p>
<p>Both <code>URLParameterVersioning</code> and <code>NamespaceVersioning</code> are reasonable if you just need a simple versioning scheme. The <code>URLParameterVersioning</code> approach might be better suitable for small ad-hoc projects, and the <code>NamespaceVersioning</code> is probably easier to manage for larger projects.</p>
<p>Note that the first group is enclosed in brackets, indicating that this is the matched portion of the hostname.</p>
<p>The <code>HostNameVersioning</code> scheme can be awkward to use in debug mode as you will typically be accessing a raw IP address such as <code>127.0.0.1</code>. There are various online services which you to <ahref="https://reinteractive.net/posts/199-developing-and-testing-rails-applications-with-subdomains">access localhost with a custom subdomain</a> which you may find helpful in this case.</p>
<p>Hostname based versioning can be particularly useful if you have requirements to route incoming requests to different servers based on the version, as you can configure different DNS records for different API versions.</p>
<p>If your versioning scheme is based on the request URL, you will also want to alter how versioned URLs are determined. In order to do so you should override the <code>.reverse()</code> method on the class. See the source code for examples.</p>
