Browsing the API

With the recent edits, we made it possible for our API to use the default content renderers configured in Django REST Framework, and therefore, our API is capable of rendering the text/html content. We can take advantage of the browsable API, a feature included in Django REST Framework that generates human-friendly HTML output for each resource whenever the request specifies text/html as the value for the Content-type key in the request header.

Whenever we enter a URL for an API resource in a web browser, the browser will require an HTML response, and therefore, Django REST Framework will provide an HTML response built with Bootstrap (http://getbootstrap.com). This response will include a section that displays the resource content in JSON, buttons to perform different requests, and forms to submit data to the resources. As everything in Django REST Framework, we can customize the templates and themes used to generate the browsable API.

Open a web browser and enter http://localhost:8000/games/. The browsable API will compose and send a GET request to /games/ and will display the results of its execution, that is, the headers and the JSON games list. The following screenshot shows the rendered web page after entering the URL in a web browser with the resource description-Game List:

Tip

If you decide to browse the API in a web browser running on another computer or device connected to the LAN, remember that you have to use the development computer's assigned IP address instead of localhost. For example, if the computer's assigned IPv4 IP address is 192.168.1.106, instead of http://localhost:8000/games/, you should use http://192.168.1.106:8000/games/. Of course, you can also use the host name instead of the IP address.

The browsable API uses the information about the allowed methods for a resource to provide us with buttons to run these methods. At the right-hand side of the resource description, the browsable API shows an OPTIONS button and a GET drop-down button. The OPTIONS button allows us to make an OPTIONS request to /games/, that is, to the current resource. The GET drop-down button allows us to make a GET request to /games/ again. If we click on or tap the down arrow, we can select the json option and the browsable API will display the raw JSON result of a GET request to /games/ without the headers.

At the bottom of the rendered web page, the browsable API provides us some control to generate a POST request to /games/. The Media type dropdown allows us to select between the configured supported parsers for our API:

• application/json
• application/x-www-form-urlencoded
• multipart/form-data

The Content textbox allows us to specify the data to be sent to the POST request formatted as specified in the Media type dropdown. Select application/json in the Media type dropdown and enter the following JSON content in the Content textbox:

{ 
    "name": "Chuzzle 2", 
    "release_date": "2016-05-18T03:02:00.776594Z", 
    "game_category": "2D mobile", 
    "played": false 
} 

Click or tap on POST. The browsable API will compose and send a POST request to /games/ with the previously specified data as JSON, and we will see the results of the call in the web browser.

The following screenshot shows a web browser displaying the HTTP status code 201 Created in the response and the previously explained dropdown and textbox with the POST button to allow us to continue composing and sending POST requests to /games/:

Now, enter the URL for an existing game resource, such as http://localhost:8000/games/2/. Make sure you replace 2 with the id or primary key of an existing game in the previously rendered Games List. The browsable API will compose and send a GET request to /games/2/ and will display the results of its execution, that is, the headers and the JSON data for the game.

The following screenshot shows the rendered web page after entering the URL in a web browser with the resource description-Game Detail:

Tip

The browsable API feature allows us to easily check how the API works and to compose and send HTTP requests with different methods to any web browser that has access to our LAN. We will take advantage of the additional features included in the browsable API, such as HTML forms that allow us to easily create new resources, later, after we build a new RESTful API with Python and Django REST Framework.