How's it looking?

Go ahead and test the API from the command line, as we did in tutorial part 1. Everything is working pretty similarly, although we've got some nicer error handling if we send invalid requests.

We can get a list of all of the snippets, as before.

  1. http http://127.0.0.1:8000/snippets/
  3. HTTP/1.1 200 OK
  4. ...
  5. [
  6.   {
  7.     "id": 1,
  8.     "title": "",
  9.     "code": "foo = \"bar\"\n",
  10.     "linenos": false,
  11.     "language": "python",
  12.     "style": "friendly"
  13.   },
  14.   {
  15.     "id": 2,
  16.     "title": "",
  17.     "code": "print(\"hello, world\")\n",
  18.     "linenos": false,
  19.     "language": "python",
  20.     "style": "friendly"
  21.   }
  22. ]

We can control the format of the response that we get back, either by using the Accept header:

  1. http http://127.0.0.1:8000/snippets/ Accept:application/json  # Request JSON
  2. http http://127.0.0.1:8000/snippets/ Accept:text/html         # Request HTML

Or by appending a format suffix:

  1. http http://127.0.0.1:8000/snippets.json  # JSON suffix
  2. http http://127.0.0.1:8000/snippets.api   # Browsable API suffix

Similarly, we can control the format of the request that we send, using the Content-Type header.

  1. # POST using form data
  2. http --form POST http://127.0.0.1:8000/snippets/ code="print(123)"
  4. {
  5.   "id": 3,
  6.   "title": "",
  7.   "code": "print(123)",
  8.   "linenos": false,
  9.   "language": "python",
  10.   "style": "friendly"
  11. }
  13. # POST using JSON
  14. http --json POST http://127.0.0.1:8000/snippets/ code="print(456)"
  16. {
  17.     "id": 4,
  18.     "title": "",
  19.     "code": "print(456)",
  20.     "linenos": false,
  21.     "language": "python",
  22.     "style": "friendly"
  23. }

If you add a —debug switch to the http requests above, you will be able to see the request type in request headers.

Now go and open the API in a web browser, by visiting http://127.0.0.1:8000/snippets/.

Browsability

Because the API chooses the content type of the response based on the client request, it will, by default, return an HTML-formatted representation of the resource when that resource is requested by a web browser. This allows for the API to return a fully web-browsable HTML representation.

Having a web-browsable API is a huge usability win, and makes developing and using your API much easier. It also dramatically lowers the barrier-to-entry for other developers wanting to inspect and work with your API.

See the browsable api topic for more information about the browsable API feature and how to customize it.