Migrating from API V1
=====================

The main differences between V1 and V2 API will be highlighted based on a concrete workflow example:

1. add the project,
2. add a tag to it,
3. upload media to it,
4. enqueue and transcribe it,
5. download the transcription,
6. share it with another user.

Authentication
--------------

Unlike in API V1, there is no longer an option to manually log in and receive an authorization token. Instead, every API enabled account has a *pregenerated API token* that should be used with each request.

Where to find the token and how to use it is described separately in :doc:`authentication`.

.. note::

    This change simplifies usage of the API by freeing the user of the login workflow step.

Adding the project
------------------

Apart from changing the endpoint path, the adding of a project can be left as is for V1. The only change from API V1 is the addition of new optional initialization parameters. Both the new endpoint path and the new parameters can be found at :doc:`projects/00-add_project`.

.. note::

    In API V2 a project is *added* instead of *created*.

The first major change in V2 API is the unified wrapping of responses. The details alongside examples are shown in :doc:`unified_response`. This means that the parsing of all endpoint responses will have to be modified to account for this.

.. tip::

    All json endpoint responses use the unified wrapping. It is recommended to define a helper utility to unwrap response data before using it.

Adding a project tag
--------------------

Project tags are no longer part of the project's metadata. As such, the endpoint has moved and no longer includes the *metadata* directory. The tag name has also moved from the query to the body. See :doc:`tags/00-add_tag` for the full details.

Upload media to the project
---------------------------

The uploading endpoints were not part of the public V1 documentation and should be carefully examined and tested when migrating. In this documentation, the simpliest method of uploading is described in :doc:`transcription/00-upload_media_file`.

.. tip::

    Uploads via TUS or websockets are provided for cases when huge media files have to be upload or there is frequent trouble with maintaining a stable network connection.

Enqueue and transcribe a project
--------------------------------

The idea of enqueing a project is unchanged in the new API. The main changes are of the technical sort, with project id moving to be part of the endpoint path and multiple new parameters becoming available. All of this can be seen in :doc:`transcription/01-enqueue_project`.

.. tip::

    A project can be enqueued automatically at a specified date and time when adding a new project with the new initialization paramaters.

.. caution::

    The moving about of parameters in the new API is rather common. This is especially true of *sensitive* data, such as IDs or emails, as they had to be moved from the visible path to the SSL encrypted body.

Download the project transcription
----------------------------------

The transcription's name has been simplified from *CurrentTrsx* to *Trsx* to stop further confusion between the original and current trsx that appeared in API V1. The full endpoint alongside the new path name reflecting this change is at :doc:`files/01-get_trsx`.

.. note::

    In API V2 the transcription is *download* instead of *exported* as there is no data conversion. The transcription is part of the project as is.

Share the project with other users
----------------------------------

Sharing the project remains the same, with the exception of the target user email moving to the json body. See :doc:`sharing/00-share_project` for the full endpoint specification.

.. note::

    Just as in API V1, the account that initiates the sharing action has to be sharing-enabled.