More complex APIs: Upload and Download Files with Flask
=======================================================

This example demonstrates uploading and downloading files to and from a Flask
API.

Python Source Code
------------------

.. literalinclude:: flask_file_upload_download.py

Deployment
----------

Assuming that you store this file as ``myapi.py`` to ``/project/myapidirectory``
in your project workspace, create an API in Faculty with the following
settings:

* **Type:** Flask
* **Working Directory:** ``/project/myapidirectory``
* **Python module:** ``myapi``
* **Python object:** ``api``

Usage
-----

Once you've spun up a development server for your API in Faculty, get the
URL and API Key for the server for the interface. Then, using Python
``requests`` (or any other suitable HTTP client), you can list the files on the
server with:

.. code-block:: python

    import requests

    API_URL = 'https://cube-64e0d7d8-1a3d-4fec-82da-fa7afea9138e.api.my.faculty.ai'
    API_KEY = 'i0cgsdYL3hpeOGkoGmA2TxzJ8LbbU1HpbkZo8B3kFG2bRKjx3V'

    headers = {'UserAPI-Key': API_KEY}

    response = requests.get('{}/files'.format(API_URL), headers=headers)

    response.json()
    >>> ['file1.txt', 'data.csv']

Upload new files with ``requests.post()``:

.. code-block:: python

    with open('newdata.csv') as fp:
        content = fp.read()

    response = requests.post(
        '{}/files/newdata.csv'.format(API_URL), headers=headers, data=content
    )

    response.status_code
    >>> 201

And download them with ``requests.get()``:

.. code-block:: python

    response = requests.get(
        '{}/files/newdata.csv'.format(API_URL), headers=headers
    )

    response.text
    >>> '1,Joe Bloggs,27\n'