def api_media_post(auth_user=None, api_core=None, request=None):
    u"""
    Register a media asset and add informations about it.

    This method only register already uploaded media asset to the shared storage.
    For example, the WebUI will upload a media asset to uploads path **before** registering it with this method.

    Medias in the shared storage are renamed with the following convention:
        ``storage_root``/medias/``user_id``/``media_id``

    When published or downloaded, media asset file-name will be ``filename``.
    Spaces ( ) are not allowed and they will be converted to underscores (_).

    Media asset's ``metadata`` must contain any valid JSON string. Only the ``title`` key is required.
    The orchestrator will automatically add ``add_date`` and ``duration`` to ``metadata``.

    .. note::

        Registration of external media assets (aka. http://) will be an interesting improvement.
    """
    data = get_request_data(request, qs_only_first_value=True)
    media = Media(user_id=auth_user._id, uri=data[u'uri'], filename=data[u'filename'], metadata=data[u'metadata'],
                  status=Media.READY)
    api_core.save_media(media)
    return ok_200(media, include_properties=True)

def api_user_post(auth_user=None, api_core=None, request=None):
    u"""Add a user."""
    data = get_request_data(request, qs_only_first_value=True)
    user = User(first_name=data[u'first_name'], last_name=data[u'last_name'], mail=data[u'mail'],
                secret=data[u'secret'], admin_platform=data[u'admin_platform'])
    api_core.save_user(user, hash_secret=True)
    delattr(user, u'secret')  # do not send back user's secret
    return ok_200(user, include_properties=True)

def api_publisher_task_head(auth_user=None, api_core=None, request=None):
    u"""
    Return an array containing the publication tasks serialized as JSON.

    The publication tasks attributes are appended with the Celery's ``async result`` of the tasks.
    """
    data = get_request_data(request, accepted_keys=api_core.db_find_keys, qs_only_first_value=True, optional=True)
    return ok_200(api_core.get_publisher_tasks(**data), include_properties=True)

def view_transform_profiles_list(request):
    u"""Show the transformation profiles list page."""
    try:
        data = get_request_data(request, accepted_keys=api_core.db_find_keys, qs_only_first_value=True, optional=True)
        return {u'profiles': remove_underscores(api_core.get_transform_profiles(**data)), u'refresh_rate': 5}
    except Exception as e:
        logging.exception(e)
        return {u'errors': [unicode(e)], u'refresh_rate': 30}

def view_medias_list(request):
    u"""Show the media assets list page."""
    try:
        data = get_request_data(request, accepted_keys=api_core.db_find_keys, qs_only_first_value=True, optional=True)
        data.setdefault(u'skip', 50)  # ask for the last 50 media assets if skip is not provided
        return {u'medias': remove_underscores(api_core.get_medias(**data)), u'refresh_rate': 5}
    except Exception as e:
        logging.exception(e)
        return {u'errors': [unicode(e)], u'refresh_rate': 30}

def api_media_get(auth_user=None, api_core=None, request=None):
    u"""
    Return an array containing the informations about the media assets serialized to JSON.

    All ``thing_id`` fields are replaced by corresponding ``thing``.
    For example ``user_id`` is replaced by ``user``'s data.
    """
    data = get_request_data(request, accepted_keys=api_core.db_find_keys, qs_only_first_value=True, optional=True)
    return ok_200(api_core.get_medias(load_fields=True, **data), include_properties=True)

def view_publisher_tasks_launch(request):
    u"""Launch a publication task."""
    try:
        auth_user = request.args.get(u'ebuio_u_pk') or request.form.get(u'ebuio_u_pk')
        data = get_request_data(request, qs_only_first_value=True)
        task_id = api_core.launch_publisher_task(user_id=auth_user, media_id=data[u'media_id'], send_email=False,
                                                 queue=data[u'queue'], callback_url=u'/publisher/callback')
        return {u'infos': [u"Publication task '{0}' was launched successfully.".format(task_id)]}
    except Exception as e:
        logging.exception(e)
        return {u'errors': [unicode(e)]}

def api_publisher_task_get(auth_user=None, api_core=None, request=None):
    u"""
    Return an array containing the publication tasks serialized to JSON.

    The publication tasks attributes are appended with the Celery's ``async result`` of the tasks.

    All ``thing_id`` fields are replaced by corresponding ``thing``.
    For example ``user_id`` is replaced by ``user``'s data.
    """
    data = get_request_data(request, accepted_keys=api_core.db_find_keys, qs_only_first_value=True, optional=True)
    return ok_200(api_core.get_publisher_tasks(load_fields=True, **data), include_properties=True)

def view_transform_profiles_add(request):
    u"""Add a transformation profile."""
    try:
        data = get_request_data(request, qs_only_first_value=True)
        profile = TransformProfile(title=data[u'title'], description=data[u'description'],
                                   encoder_name=data[u'encoder_name'], encoder_string=data[u'encoder_string'])
        api_core.save_transform_profile(profile)
        return {u'infos': [u"Profile '{0}' was created successfully.".format(profile.title)]}
    except Exception as e:
        logging.exception(e)
        return {u'errors': [unicode(e)]}

def api_media_id_patch(id=None, auth_user=None, api_core=None, request=None):
    u"""Update the informations of a media asset (only metadata field can be updated)."""
    media = api_core.get_media(spec={u'_id': id})
    data = get_request_data(request, qs_only_first_value=True)
    if not media:
        raise IndexError(to_bytes(u'No media asset with id {0}.'.format(id)))
    if auth_user._id != media.user_id:
        flask.abort(403, u'You are not allowed to modify media asset with id {0}.'.format(id))
    if u'metadata' in data:
        media.metadata = data[u'metadata']
    api_core.save_media(media)
    return ok_200(u'The media asset "{0}" has been updated.'.format(media.filename), include_properties=False)

def api_revoke_publisher_task_hook(auth_user=None, api_core=None, request=None):
    u"""
    This method is called by publication workers when they finish their work (revoke).

    If the task is successful, the orchestrator will update media asset's ``status`` and ``public_uris`` attribute.
    Else, the orchestrator will append ``error_details`` to ``statistic`` attribute of the task.
    """
    data = get_request_data(request, qs_only_first_value=True)
    task_id, publish_uri, status = data[u'task_id'], data.get(u'publish_uri'), data[u'status']
    logging.debug(u'task {0}, revoked publish_uri {1}, status {2}'.format(task_id, publish_uri, status))
    api_core.publisher_revoke_callback(task_id, publish_uri, status)
    return ok_200(u'Your work is much appreciated, thanks !', include_properties=False)

def view_publisher_tasks(request):
    u"""Show the publication tasks home page."""
    try:
        data = get_request_data(request, accepted_keys=api_core.db_find_keys, qs_only_first_value=True, optional=True)
        data.setdefault(u'skip', 50)  # ask for the last 50 media assets if skip is not provided
        data.setdefault(u'spec', {u'status': Media.READY})  # filter the media assets that cannot be published
        # FIXME add more filters
        medias = remove_underscores(api_core.get_medias(**data))
        queues = remove_underscores(api_core.get_publisher_queues())
        return {u'medias': medias, u'queues': queues}
    except Exception as e:
        logging.exception(e)
        return {u'errors': [unicode(e)]}

def view_transform_tasks_launch(request):
    u"""Launch a transformation task."""
    try:
        auth_user = request.args.get(u'ebuio_u_pk') or request.form.get(u'ebuio_u_pk')
        data = get_request_data(request, qs_only_first_value=True)
        task_id = api_core.launch_transform_task(
            user_id=auth_user, media_in_id=data[u'media_in_id'], profile_id=data[u'profile_id'],
            filename=data[u'filename'], metadata={u'title': data[u'title']}, send_email=False, queue=data[u'queue'],
            callback_url=u'/transform/callback')
        return {u'task_id': task_id}
    except Exception as e:
        logging.exception(e)
        return {u'errors': [unicode(e)]}

def view_publisher_tasks_list(request):
    u"""Show the publication tasks list page."""
    try:
        data = get_request_data(request, accepted_keys=api_core.db_find_keys, qs_only_first_value=True, optional=True)
        data.setdefault(u'skip', 50)  # ask for the last 50 media assets if skip is not provided
        tasks = remove_underscores(api_core.get_publisher_tasks(**data))
        for task in tasks:
            task.media = remove_underscores(api_core.get_media(spec={u'_id': task.media_id}))
            task.statistic[u'elapsed_time'] = secs_to_time(task.statistic.get(u'elapsed_time', 0)).strftime(u'%H:%M:%S')
            task.statistic[u'eta_time'] = secs_to_time(task.statistic.get(u'eta_time', 0)).strftime(u'%H:%M:%S')
        return {u'tasks': tasks, u'refresh_rate': 5}
    except Exception as e:
        logging.exception(e)
        return {u'errors': [unicode(e)], u'refresh_rate': 30}

def api_transform_task_hook(auth_user=None, api_core=None, request=None):
    u"""
    This method is called by transformation workers when they finish their work.

    If task is successful, the orchestrator will set media's status to READY.
    Else, the orchestrator will append ``error_details`` to ``statistic`` attribute of task.

    The media asset will be deleted if task failed (even the worker already take care of that).
    """
    data = get_request_data(request, qs_only_first_value=True)
    task_id, status = data[u'task_id'], data[u'status']
    logging.debug(u'task {0}, status {1}'.format (task_id, status))
    api_core.transform_callback(task_id, status)
    return ok_200(u'Your work is much appreciated, thanks !', include_properties=False)

def api_transform_profile_post(auth_user=None, api_core=None, request=None):
    u"""
    Add a transformation profile.

    The transformation profile's ``encoder_name`` attribute can be the following :

    * **copy** to bypass FFmpeg and do a simple file block copy ;
    * **ffmpeg** to transcode a media asset to another with FFMpeg ;
    * **dashcast** to transcode a media asset to MPEG-DASH with DashCast ;
    """
    data = get_request_data(request, qs_only_first_value=True)
    profile = TransformProfile(title=data[u'title'], description=data[u'description'],
                               encoder_name=data[u'encoder_name'], encoder_string=data[u'encoder_string'])
    api_core.save_transform_profile(profile)
    return ok_200(profile, include_properties=True)

def api_publisher_task_post(auth_user=None, api_core=None, request=None):
    u"""
    Launch a publication task.

    Any user can launch a publication task using any media asset as input.
    This is linked to media asset API methods access policy.

    The orchestrator will automatically add ``add_date`` to ``statistic``.

    .. note::

        Interesting enhancements would be to :

        * Schedule tasks by specifying start time (...)
        * Handle the registration of tasks related to PENDING medias
        * Permit to publication a media asset on more than one (1) publication queue
    """
    data = get_request_data(request, qs_only_first_value=True)
    task_id = api_core.launch_publisher_task(auth_user._id, data[u'media_id'], data[u'send_email'], data[u'queue'],
                                             u'/publisher/callback')
    return ok_200(task_id, include_properties=True)

def api_user_id_patch(id=None, auth_user=None, api_core=None, request=None):
    u"""
    Update an user.

    User's admin_platform attribute can only be modified by root or any authenticated user with admin_platform attribute
    set.
    """
    user = api_core.get_user(spec={u'_id': id})
    data = get_request_data(request, qs_only_first_value=True)
    if not user:
        raise IndexError(to_bytes(u'No user with id {0}.'.format(id)))
    old_name = user.name
    if u'first_name' in data:
        user.first_name = data[u'first_name']
    if u'last_name' in data:
        user.last_name = data[u'last_name']
    if u'mail' in data:
        user.mail = data[u'mail']
    if u'secret' in data:
        user.secret = data[u'secret']
    if auth_user.admin_platform and u'admin_platform' in data:
        user.admin_platform = data[u'admin_platform']
    api_core.save_user(user, hash_secret=True)
    return ok_200(u'The user "{0}" has been updated.'.format(old_name), include_properties=False)

def api_transform_task_post(auth_user=None, api_core=None, request=None):
    u"""
    Launch a transformation task.

    Any user can launch a transformation task using any media asset as input and any transformation profile.
    This is linked to media assets and transformation profile API methods access policies.

    The output media asset is registered to the database with the PENDING status and the ``parent_id`` field is set to
    input media asset's ``id``. This permit to know relation between media assets !

    The orchestrator will automatically add ``add_date`` to ``statistic``.

    .. note::

        Interesting enhancement would be to :

        * Schedule obs by specifying start time (...) ;
        * Handle the registration of tasks related to PENDING medias ;
    """
    data = get_request_data(request, qs_only_first_value=True)
    task_id = api_core.launch_transform_task(
        auth_user._id, data[u'media_in_id'], data[u'profile_id'], data[u'filename'], data[u'metadata'],
        data[u'send_email'], data[u'queue'], u'/transform/callback')
    return ok_200(task_id, include_properties=True)

def api_environment_post(auth_user=None, api_core=None, request=None):
    u"""Add a new environment."""
    data = get_request_data(request, qs_only_first_value=True)
    return ok_200(api_core.add_environment(data[u'name'], data[u'type'], data[u'region'], data[u'access_key'],
                  data[u'secret_key'], data[u'control_bucket']), include_properties=False)