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.