From e77afeee37be59d02af39cf4e743362d5fad048f Mon Sep 17 00:00:00 2001
From: Roberto Rosario <roberto.rosario.gonzalez@gmail.com>
Date: Thu, 4 Apr 2019 02:32:02 -0400
Subject: [PATCH] Add API client examples

Signed-off-by: Roberto Rosario <roberto.rosario.gonzalez@gmail.com>
---
 docs/chapters/api.rst | 74 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)

diff --git a/docs/chapters/api.rst b/docs/chapters/api.rst
index 30872ecb6c..4c542ae163 100644
--- a/docs/chapters/api.rst
+++ b/docs/chapters/api.rst
@@ -26,3 +26,77 @@ endpoints are structured by resource type. Examples:
 
 The API supports the HTTP verbs: **GET**, **POST**, **PUT**, **PATCH**,
 and **DELETE**.
+
+
+Example use
+===========
+
+Install Python Requests (http://docs.python-requests.org/en/master/)::
+
+    pip install requests
+
+Get a list of document types::
+
+    import requests
+
+    requests.get('http://127.0.0.1:8000/api/document_types/', auth=('username', 'password')).json()
+
+    {u'count': 1,
+     u'next': None,
+     u'previous': None,
+     u'results': [{u'delete_time_period': 30,
+       u'delete_time_unit': u'days',
+       u'documents_count': 12,
+       u'documents_url': u'http://127.0.0.1:8000/api/document_types/1/documents/',
+       u'filenames': [],
+       u'id': 1,
+       u'label': u'Default',
+       u'trash_time_period': None,
+       u'trash_time_unit': None,
+       u'url': u'http://127.0.0.1:8000/api/document_types/1/'}]}
+
+Upload a new document::
+
+    with open('test_document.pdf', mode='rb') as
+        requests.post('http://127.0.0.1:8000/api/documents/', auth=('username', 'password'), files={'file': file_object}, data={'document_type': 1}).json()
+
+    {u'description': u'',
+    u'document_type': 1,
+    u'id': 19,
+    u'label': u'test_document.pdf',
+    u'language': u'eng'}
+
+Use API tokens to avoid sending the username and password on every request. Obtain a token by making a POST request to ``/api/auth/token/obtain/?format=json``::
+
+    requests.post('http://127.0.0.1:8000/api/auth/token/obtain/?format=json', data={'username': 'username', 'password': 'password'}).json()
+
+    {u'token': u'4ccbc35b5eb327aa82dc3b7c9747b578900f02bb'}
+
+Add the API token to the request header::
+
+    headers = {'Authorization': 'Token 4ccbc35b5eb327aa82dc3b7c9747b578900f02bb'}
+
+    requests.get('http://127.0.0.1:8000/api/document_types/', headers=headers).json()
+
+    {u'description': u'',
+    u'document_type': 1,
+    u'id': 19,
+    u'label': u'test_document.pdf',
+    u'language': u'eng'}
+
+
+Use sessions to avoid having to add the headers on each request::
+
+    session = requests.Session()
+
+    headers = {'Authorization': 'Token 4ccbc35b5eb327aa82dc3b7c9747b578900f02bb'}
+
+    session.headers.update(headers)
+
+    session.get('http://127.0.0.1:8000/api/document_types/')
+
+    {u'description': u'',
+    u'document_type': 1,
+    u'id': 19,
+    u'label': u'test_document.pdf',
+    u'language': u'eng'}