.. _get_mime_type:

Method: Detect MIME Type
-------------------------

Description
~~~~~~~~~~~

Detects the MIME type of a file from the first 64 bytes of its content plus
the file extension. Intended to be called before uploading a file object to
determine the correct MIME type for storage.

Certain extension and type combinations are resolved to more specific MIME 
types (e.g. a ``.key`` ZIP is identified as ``application/vnd.apple.keynote``).

Optionally reports whether the intended file size exceeds the server's upload limit.

URL Syntax
~~~~~~~~~~

/api/{version}/utils/get_mime_type

HTTP Method
~~~~~~~~~~~

POST

Successful HTTP Response
~~~~~~~~~~~~~~~~~~~~~~~~

200

Parameters
~~~~~~~~~~

+----------------+-----------------------------------------------------------+----------------+--------+-----------+-------------------------------------+
| Parameter name | Description                                               | Parameter type | Type   | Mandatory | Comment                             |
+================+===========================================================+================+========+===========+=====================================+
| X-Http-Token   | StoredSafe token                                          | HTTP Header    | String | Yes       |                                     |
+----------------+-----------------------------------------------------------+----------------+--------+-----------+-------------------------------------+
| data           | First 64 bytes of the file, Base64-encoded                | JSON-encoded   | String | Yes       | Maximum 64 bytes after decode       |
+----------------+-----------------------------------------------------------+----------------+--------+-----------+-------------------------------------+
| extension      | File extension without leading dot (e.g. ``pdf``)         | JSON-encoded   | String | Yes       | Maximum 25 characters               |
+----------------+-----------------------------------------------------------+----------------+--------+-----------+-------------------------------------+
| size           | Intended total file size in bytes                         | JSON-encoded   | Integer| No        | Used to check against upload limit  |
+----------------+-----------------------------------------------------------+----------------+--------+-----------+-------------------------------------+

Response Attributes
~~~~~~~~~~~~~~~~~~~

+---------------------+------------------------------------------------------+---------+
| Attribute           | Description                                          | Type    |
+=====================+======================================================+=========+
| CALLINFO.status     | SUCCESS or FAIL                                      | String  |
+---------------------+------------------------------------------------------+---------+
| CALLINFO.token      | StoredSafe token to be used in subsequent calls      | String  |
+---------------------+------------------------------------------------------+---------+
| CALLINFO.handler    | Handler used                                         | String  |
+---------------------+------------------------------------------------------+---------+
| CALLINFO.errors     | Number of errors                                     | Integer |
+---------------------+------------------------------------------------------+---------+
| CALLINFO.errorcodes | Number of error codes                                | Integer |
+---------------------+------------------------------------------------------+---------+
| RESULT.mimetype     | Detected MIME type string                            | String  |
+---------------------+------------------------------------------------------+---------+
| RESULT.size         | Intended file size supplied by caller                | Integer |
+---------------------+------------------------------------------------------+---------+
| RESULT.max_file_size| Server maximum upload size in bytes                  | Integer |
+---------------------+------------------------------------------------------+---------+

Example
~~~~~~~

Detect the MIME type of a PDF file.

**Request**

::

    POST /api/1.0/utils/get_mime_type
    X-Http-Token: your_storedsafe_token
    Content-Type: application/json
    {
        "data": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9DYXRhbG9nCi9QYWdlcyAy",
        "extension": "pdf",
        "size": 204800
    }

**Response**

::

    HTTP/2 200
    Content-Type: application/json
    {
        "CALLINFO": {
            "errorcodes": 0,
            "errors": 0,
            "general": [],
            "handler": "UtilsHandler",
            "status": "SUCCESS",
            "token": "rotated_storedsafe_token"
        },
        "DATA": { ... },
        "HEADERS": { ... },
        "PARAMS": [],
        "RESULT": {
            "mimetype": "application/pdf",
            "size": 204800,
            "max_file_size": 52428800
        }
    }