Migrating from API V1
The main differences between V1 and V2 API will be highlighted based on a concrete workflow example:
add the project,
add a tag to it,
upload media to it,
enqueue and transcribe it,
download the transcription,
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 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 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 Unified Responses. 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 Add project 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 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 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 Get project 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.