In Chapter 4, Using Generalized Behavior from the APIView Class, we made many changes to make it possible for the simple RESTful Web Service to work with a content negotiation class and provide many content renderers. We used the default configuration for the Django REST framework that includes a renderer that produces text/html content.

The rest_framework.response.BrowsableAPIRenderer class is responsible for rendering the text/html content. This class makes it possible for us to browse the API. The Django REST framework includes a feature that generates an interactive and human-friendly HTML output for the different resources when the request specifies text/html as the value for the Content-Type key in the request header. This feature is known as the browsable API because it enables us to use a web browser to navigate through the API and easily make different types of HTTP requests.

Now, we will compose and send HTTP requests that will make the RESTful Web Service user the BrowsableAPIRenderer class to provide text/html content in the response. This way, we will understand how the browsable API works before we jump into the web browser and we start using and customizing this feature. In case you stopped Django's development server, you will have to start it again as we learned in Chapter 3, Creating API Views, in the section Launching Django's development server, to start running the Django development server.

Run the following command to retrieve all the toys with the Accept request header key set to text/html. Remember that the virtual environment we created in the previous chapters must be activated in order to run the next http command:

 http -v :8000/toys/ "Accept:text/html"

The following is the equivalent curl command:

 curl -vH "Accept: text/html" -iX GET localhost:8000/toys/

The previous commands will compose and send the following HTTP request: GET http://localhost:8000/toys/. These commands specify the text/html value for the Accept key in the request header. This way, the HTTP request indicates that it accepts a response of text/html.

In both cases, we specified the -v option that provides a verbose output and prints the details of the request that has been made. For example, the following are the first lines of the output generated by the http command:

    GET /toys/ HTTP/1.1
    Accept: text/html
    Accept-Encoding: gzip, deflate
    Connection: keep-alive
    Host: localhost:8000
    User-Agent: HTTPie/0.9.3

The second line prints the value for the Accept key included in the request header, text/html. The header response for the request will include the following line:

    Content-Type: text/html; charset=utf-8

The previous commands will compose and send the following HTTP request: GET http://localhost:8000/toys/. The request will end up running the views.toy_list function, that is, the toy_list function declared within the toys/views.py file. The content negotiation class selected the BrowsableAPIRenderer class to provide text/html content in the response. The following lines show the first lines of the output for the http command:

We can easily detect from the previous output that the Django REST framework provides an HTML web page as a response to our previous requests. If we enter any URL for a resource collection or resource in any web browser, the browser will perform an HTTP GET request that requires an HTML response, that is, the Accept request header key will be set to text/html. The web service built with the Django REST framework will provide an HTML response and the browser will render the web page.

By default, the BrowsableAPIRenderer class uses the Bootstrap popular frontend component library. You can read more about Bootstrap here: http://getbootstrap.com. The web page might include the following elements:

• Diverse buttons to perform other requests to the resource or resource collection
• A section that displays the resource or resource collection content in JSON
• Forms with fields that allow us to submit data for POST, PUT, and PATCH requests

The Django REST framework uses templates and themes to render the pages for the browsable API. It is possible to customize many settings to tailor the output to our specific requirements.