Running tests to check that versioning works as expected

Now, we can launch Django's development server to compose and send HTTP requests to understand how the configured versioning scheme works. Execute any of the following two commands based on your needs to access the API in other devices or computers connected to your LAN. Remember that we analyzed the difference between them in Chapter 3, Creating API Views, in the Launching Django's development server section.

    python manage.py runserver
    python manage.py runserver 0.0.0.0:8000

After we run any of the previous commands, the development server will start listening at port 8000.

Now, we will compose and send an HTTP GET request to retrieve the first page of the drone categories by working with the first version of our RESTful Web Service:

    http :8000/v1/drone-categories/

The following is the equivalent curl command:

    curl -iX GET localhost:8000/v1/drone-categories/

The previous commands will compose and send the following HTTP request: GET http://localhost:8000/v1/drone-categories/. The request URL starts with v1/ after the domain and the port number (http://localhost:8000/), and therefore, it will match the '^v1/' regular expression and will test the regular expressions defined in the restful01/drones/urls.py file and will work with a namespace equal to 'v1'. Then, the URL without the version prefix ('v1/') will match the 'drone-categories/$'regular expression and run the get method for the views.DroneCategoryList class-based view.

The NamespaceVersioning class makes sure that the rendered URLs include the appropriate version prefix in the response. The following lines show a sample response for the HTTP request, with the first and only page of drone categories. Notice that the URLs for the drones list for each category include the version prefix. In addition, the value of the url key for each drone category includes the version prefix.

    HTTP/1.0 200 OK
    Allow: GET, POST, HEAD, OPTIONS
    Content-Length: 670
    Content-Type: application/json
    Date: Sun, 03 Dec 2017 19:34:13 GMT
    Server: WSGIServer/0.2 CPython/3.6.2
    Vary: Accept, Cookie
    X-Frame-Options: SAMEORIGIN
    
    {
        "count": 2, 
        "next": null, 
        "previous": null, 
        "results": [
            {
                "drones": [
                    "http://localhost:8000/v1/drones/6", 
                    "http://localhost:8000/v1/drones/4", 
                    "http://localhost:8000/v1/drones/8", 
                    "http://localhost:8000/v1/drones/10"
                ], 
                "name": "Octocopter", 
                "pk": 2, 
                "url": "http://localhost:8000/v1/drone-categories/2"
            }, 
            {
                "drones": [
                    "http://localhost:8000/v1/drones/2", 
                    "http://localhost:8000/v1/drones/9", 
                    "http://localhost:8000/v1/drones/5", 
                    "http://localhost:8000/v1/drones/7", 
                    "http://localhost:8000/v1/drones/3", 
                    "http://localhost:8000/v1/drones/12", 
                    "http://localhost:8000/v1/drones/11", 
                    "http://localhost:8000/v1/drones/1"
                ], 
                "name": "Quadcopter", 
                "pk": 1, 
                "url": "http://localhost:8000/v1/drone-categories/1"
            }
        ]
    }

Now, we will compose and send an HTTP GET request to retrieve the first page of the vehicle categories by working with the second version of our RESTful Web Service:

    http :8000/v2/vehicle-categories/

The following is the equivalent curl command:

    curl -iX GET localhost:8000/v2/vehicle-categories/

The previous commands will compose and send the following HTTP request: GET http://localhost:8000/v2/vehicle-categories/. The request URL starts with v2/ after the domain and the port number (http://localhost:8000/), and therefore, it will match the '^v2/' regular expression and will test the regular expressions defined in the restful01/drones/v2/urls.py file and will work with a namespace equal to 'v2'. Then, the URL without the version prefix ('v2/') will match the 'vehicle-categories/$'regular expression and run the get method for the views.DroneCategoryList class-based view.

As happened with the previous request, the NamespaceVersioning class makes sure that the rendered URLs include the appropriate version prefix in the response. The following lines show a sample response for the HTTP request, with the first and only page of vehicle categories. We haven't made changes to the serializer in the new version, and therefore, each category will render a list named drones. However, the URLs for the drones list for each category include the version prefix and they use the appropriate URL with a vehicle in the URL instead of a drone. In addition, the value of the url key for each vehicle category includes the version prefix.

    HTTP/1.0 200 OK
    Allow: GET, POST, HEAD, OPTIONS
    Content-Length: 698
    Content-Type: application/json
    Date: Sun, 03 Dec 2017 19:34:29 GMT
    Server: WSGIServer/0.2 CPython/3.6.2
    Vary: Accept, Cookie
    X-Frame-Options: SAMEORIGIN
    
    {
        "count": 2, 
        "next": null, 
        "previous": null, 
        "results": [
            {
                "drones": [
                    "http://localhost:8000/v2/vehicles/6", 
                    "http://localhost:8000/v2/vehicles/4", 
                    "http://localhost:8000/v2/vehicles/8", 
                    "http://localhost:8000/v2/vehicles/10"
                ], 
                "name": "Octocopter", 
                "pk": 2, 
                "url": "http://localhost:8000/v2/vehicle-categories/2"
            }, 
            {
                "drones": [
                    "http://localhost:8000/v2/vehicles/2", 
                    "http://localhost:8000/v2/vehicles/9", 
                    "http://localhost:8000/v2/vehicles/5", 
                    "http://localhost:8000/v2/vehicles/7", 
                    "http://localhost:8000/v2/vehicles/3", 
                    "http://localhost:8000/v2/vehicles/12", 
                    "http://localhost:8000/v2/vehicles/11", 
                    "http://localhost:8000/v2/vehicles/1"
                ], 
                "name": "Quadcopter", 
                "pk": 1, 
                "url": "http://localhost:8000/v2/vehicle-categories/1"
            }
        ]
    }

Open a web browser and enter http://localhost:8000/v1. The browser will compose and send a GET request to /v1 with text/html as the desired content type and the returned HTML web page will be rendered. The request will end up executing the get method defined in the ApiRoot class within the restful01/drones/views.py file. The following screenshot shows the rendered web page with the resource description: Api Root. The Api Root for the first version uses the appropriate URLs for version 1, and therefore, all the URLs start with http://localhost:8000/v1/.

Now, go to http://localhost:8000/v2. The browser will compose and send a GET request to /v2 with text/html as the desired content type and the returned HTML web page will be rendered. The request will end up executing the get method defined in the ApiRootVersion2 class within the restful01/drones/v2/views.py file. The following screenshot shows the rendered web page with the resource description: Api Root Version2. The Api Root for the first version uses the appropriate URLs for version 2, and therefore, all the URLs start with http://localhost:8000/v2/. You can check the differences with the Api Root rendered for version 1.

This new version of the Api Root renders the following hyperlinks:

http://localhost:8000/v2/vehicle-categories/: The collection of vehicle categories
http://localhost:8000/v2/vehicles/: The collection of vehicles
http://localhost:8000/v2/pilots/: The collection of pilots
http://localhost:8000/v2/competitions/: The collection of competitions

We can use all the features provided by the browsable API with the two versions we have configured.

Developing and maintaining multiple versions of a RESTful Web Service is an extremely complex task that requires a lot of planning. We must take into account the different versioning schemes that the Django REST framework provides out of the box to make our job simpler. However, it is always very important to avoid making things more complex than necessary. We should keep any versioning scheme as simple as possible and we must make sure that we continue to provide RESTful Web Services with easily identifiable resources and resource collections in the URLs.

Table of Contents for Running tests to check that versioning works as expected

Create new playlist

Sign In

Sign Up

Table of Contents for
Running tests to check that versioning works as expected