========
REST API
========

Mayan EDMS provides an HTTP REST Application Program Interface (or API). This
API allows integration with 3rd party software using simple HTTP requests.

Several API authentication methods are provides: **Session**, **Token**,
and **HTTP Basic**.

The URL for the API can be found via the :menuselection:`Tools --> REST API`
menu. The API is also self-documenting. The live API documentation can be
found in the :menuselection:`Tools --> API Documentation (Swagger)` menu for
the Swagger version and in the
:menuselection:`Tools --> API Documentation (ReDoc)` menu for the ReDoc version.

The are a few ways to structure REST APIs. In the case of Mayan EDMS, API
endpoints are structured by resource type. Examples:

* /cabinets - To view or create new cabinets
* /cabinets/<id> - To view the details, edit, or delete an existing cabinet.
* /cabinets/<id>/documents - To view, add, or remove documents from an existing
  cabinet.
* /cabinets/<id>/documents/<id> - To view, add, or remove one document from an
  existing cabinet.

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 file_object:
        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'}