Contents
- 1 Settings
- 2 Authentication
- 3 Identity Providers
- 4 Current User
- 5 Info
- 6 Organizations
- 7 Libraries
- 8 Playlists
- 9 Media Workflows
- 10 Media Library
- 11 Shared Library
- 12 Content
- 13 Filtering
- 14 Paging
- 15 Combining Filtering and Paging
Settings
There are three settings that can be configured for the API.
RequireSSL: Is SSL connection required to call the API. Default is false.
DefaultPageIndex: The default current page index. Default is 1.
DefaultPageSize: The default number of items per page. Default is 10.
You can find these in the API web.config file under the appSettings node.
The defaults look like so:
<add key="RequireSSL" value="false" /> <add key="DefaultPageIndex" value="1" /> <add key="DefaultPageSize" value="10" />
Authentication
The majority of this API requires authentication, and will only return results for items that the current user is authorized to access, for e.g. Organizations and Libraries.
Basic Authentication
The API supports basic authentication and is tied to your Ensemble Video account. Note that this must be an Ensemble Video account; accounts associated with LDAP and Shibboleth Identity Providers are not currently supported. If you require basic authentication and need to query on behalf of a user associated with an LDAP or Shibboleth account, you can set up a "service account". This is a builtin user account with elevated permissions (the account has access to a superset of information for some set of users) and to filter results by a particular user account.
Forms Authentication
Forms authentication is supported by POSTing a username, password and identity provider identifier to the login endpoint.
| Url | {ensembleWebAppUrl}/api/login |
| Example | https://cloud.ensemblevideo.com/api/login |
Parameters
| Parameter Name | Description | |
|---|---|---|
| User | Required | The username of the user to authenticate. |
| Password | Required | The password of the user to authenticate. |
| IdentityProviderID | Optional | The identifier of the identity provider which the user is associated with. Defaults to the default system builtin identity provider. Note that this value is required if the authenticating user does not belong to the default system builtin identity provider. |
| Persist | Optional | Boolean indicating whether or not the login should persist across browser sessions. Defaults to false. |
In order to logout the current user, you can POST to the logout endpoint.
| Url | {ensembleWebAppUrl}/api/logout |
| Example | https://cloud.ensemblevideo.com/api/logout |
Identity Providers
Provides a listing of available "Builtin" and LDAP identity providers supporting forms authentication across all Institutions.
| Url | {ensembleWebAppUrl}/api/identityproviders |
| Example | https://cloud.ensemblevideo.com/api/identityproviders |
Current User
Provides information about the currently authenticated user.
| Url | {ensembleWebAppUrl}/api/currentuser |
| Example | https://cloud.ensemblevideo.com/api/currentuser |
Info
Provides information regarding installation, including version number.
| Url | {ensembleWebAppUrl}/api/info |
| Example | https://cloud.ensemblevideo.com/api/info |
Organizations
Returns a list of organizations accessible by the authenticated user.
| Url | {ensembleWebAppUrl}/api/organizations |
| Example | https://cloud.ensemblevideo.com/api/organizations |
Libraries
Returns a list of libraries accessible by the authenticated user, across all organizations.
| Url | {ensembleWebAppUrl}/api/libraries |
| Example | https://cloud.ensemblevideo.com/api/libraries |
Playlists
Returns a list of playlists accessible by the authenticated user, across all libraries.
| Url | {ensembleWebAppUrl}/api/playlists |
| Example | https://cloud.ensemblevideo.com/api/playlists |
Media Workflows
Returns a list of media workflows that accept uploaded content, accessible by the authenticated user across all libraries.
| Url | {ensembleWebAppUrl}/api/mediaworkflows |
| Example | https://cloud.ensemblevideo.com/api/mediaworkflows |
Upload
Using values in the response from a query to #Media Workflows, you can create a request to upload content to Ensemble Video.
This request should be a POST to the "SubmitUrl" returned in the #Media Workflows response, using content type "multipart/form-data", file contents and the following parameters:
Parameters
| Parameter Name | Description | |
|---|---|---|
| FileData | Required | Name of the file input object that will be posted to the server. |
| FirstName | Optional | First name of the person to credit for the uploaded content. Ignored unless "LastName" and "Email" are also set. |
| LastName | Optional | Last name of the person to credit for the uploaded content. Ignored unless "FirstName" and "Email" are also set. |
| Optional | Email address of the person to credit for the uploaded content. Ignored unless "FirstName" and "LastName" are also set. | |
| UserID | Optional | The internal user identifier of the Ensemble Video account that is actually uploading the content for use in audit records (e.g. createdBy). |
| Title | Optional | Title of the uploaded content. |
| Description | Optional | Description of the uploaded content. |
| DateProduced | Optional | Date the content was produced. TODO - add example formats here. The date is converted from String to DateTime using Convert.ChangeType, current culture of en-US. |
| Keywords | Optional | Keywords to associate with the uploaded content. |
| ContentID | Optional | The identifier for an existing content item. If passed this will be added as an encoding to the existing content. |
| MediaWorkflowID | Optional* | ID of the media workflow that will process the upload (this is available in the response to a MediaWorkflows query). Required when the upload type is AudioVideo (the default). See AssetTypeID and UploadType below. |
| AssetTypeID | Optional | One of the following values "468FC738-32E8-41EA-B620-F4AECC4BD444" (Attachment), "E53D0660-8BDC-4725-8AA9-8A4225EECC3A" (AudioVideo), "1BF25DB8-BD81-44AD-8AD9-3C0A6F175105" (Caption), "155B4A48-0521-4BC4-A534-1C0870882098" (Image). By default, or if no ContentID value is provided, is assumed to be an AudioVideo upload. |
| UploadType | Optional | New in version 4.1.0 . Alternative to AssetTypeID parameter to specify type of upload. Possible values are "attachment" (Attachment), "audio" (AudioVideo), "video" (AudioVideo), "caption" (Caption) and "image" (Image). By default, or if no ContentID value is provided, is assumed to be an AudioVideo upload. |
The response to an upload request is a JSON object with the ContentID of the newly created content item, or that of the updated content item.
Media Library
Returns a list of published content from the media library in a given library, accessible by the authenticated user. As of version 4.1.0, you can request that unpublished content be included in the response as well by passing the parameter includeUnpublished=true.
If no library id is provided, as in the following example, the API will redirect and return results for the media library within the current user's "home" library
| Url | {ensembleWebAppUrl}/api/content |
| Example | https://cloud.ensemblevideo.com/api/content |
| Url | {ensembleWebAppUrl}/api/medialibrary |
| Example | https://cloud.ensemblevideo.com/api/medialibrary |
For backwards compatibility, requests to /api/content in 4.1.0+ identified as media library requests will redirect. See #Content.
Given a library id, as follows, the query will return a list of content within the media library in the given library
| Url | {ensembleWebAppUrl}/api/content/{libraryId} |
| Example | https://cloud.ensemblevideo.com/api/content/f2e41d0a-c89f-4699-9072-27c60cb731c7 |
| Url | {ensembleWebAppUrl}/api/medialibrary/{libraryId} |
| Example | https://cloud.ensemblevideo.com/api/medialibrary/f2e41d0a-c89f-4699-9072-27c60cb731c7 |
For backwards compatibility, requests to /api/content/{libraryId} in 4.1.0+ identified as media library requests will redirect. See #Content.
Returns a list of content from the shared library in a given library, accessible by the authenticated user.
If no library id is provided, as in the following example, the API will redirect and return results for the shared library within the current user's "home" library
| Url | {ensembleWebAppUrl}/api/sharedcontent |
| Example | https://cloud.ensemblevideo.com/api/sharedcontent |
| Url | {ensembleWebAppUrl}/api/sharedlibrary |
| Example | https://cloud.ensemblevideo.com/api/sharedlibrary |
For backwards compatibility, requests to /api/sharedcontent in 4.1.0+ will redirect.
Given a library id, as follows, the query will return a list of content within the shared library in the given library
| Url | {ensembleWebAppUrl}/api/sharedcontent/{libraryId} |
| Example | https://cloud.ensemblevideo.com/api/sharedcontent/f2e41d0a-c89f-4699-9072-27c60cb731c7 |
| Url | {ensembleWebAppUrl}/api/sharedlibrary/{libraryId} |
| Example | https://cloud.ensemblevideo.com/api/sharedlibrary/f2e41d0a-c89f-4699-9072-27c60cb731c7 |
For backwards compatibility, requests to /api/sharedcontent/{libraryId} in 4.1.0+ will redirect.
Content
New in version 4.1.0. For prior versions, reference #Media Library.
Provides detail regarding a particular content item.
| Url | {ensembleWebAppUrl}/content/{contentId} |
| Example | https://cloud.ensemblevideo.com/api/content/8368e0b6-5b9f-4a12-9b65-016cad60ca6e |
Example response:
{
"ID": "8368e0b6-5b9f-4a12-9b65-016cad60ca6e",
"AddedOn": "2015-10-09T16:56:32",
"Description": null,
"Title": "My Video",
"Keywords": null,
"ThumbnailUrl": "https://cloud.ensemblevideo.com/app/assets/be3e2fba-6bb4-4457-acc6-c12c1489d45c.JPG?Width=100",
"OrganizationID": "3d8e3d3c-5c49-4fd8-96fd-c28f84c81b1a",
"OrganizationName": "Ensemble Video",
"LibraryID": "8fa23df5-af30-4aec-865d-fdfb4672aba1",
"LibraryName": "System",
"IsPublished": true,
"DownloadUrl": "https://cloud.ensemblevideo.com/api/content/8368e0b6-5b9f-4a12-9b65-016cad60ca6e/download"
}
Download
Content that is downloadable will contain a DownloadUrl, as in the example response above, that can be used to stream or download the content.
It is important NOT to hardcode the DownloadUrl value. In other words, don't assume that content can always be downloaded using a url like "/api/content/{contentId}/download". This value may be unpredictable in future versions, for e.g. if support for temporary download urls is implemented.
Content is downloadable under the following conditions:
- The content is published.
- The content is not published securely (i.e. if it is only published to secure playlists, it is not downloadable).
- The content is not published and the authenticated user has editor access or above.
- The content encoding(s) is in the ready state
Download vs Stream
By default, a request to the DownloadUrl will stream the encoding. You can pass a withDisposition=true parameter in the request to the DownloadUrl to indicate that the response should include a Content-Disposition header for download.
Filtering
Query results can be filtered to only those results that the currently authenticated user and some other user would be able to see. Typically the authenticated user would have access to a superset of information that the filtered user has access to, as is the case for System, Institution and Organization administrators. The "User" parameter should be in the format {username}@{domain} where the domain matches that configured for the associated Identity Provider. Note for internal Ensemble Video acccounts simply do not append the @{domain} portion. For example:
| Url | {ensembleWebAppUrl}/api/MediaWorkflows?User=bob@example.edu |
| Example | https://cloud.ensemblevideo.com/api/MediaWorkflows?User=bob |
API query results can be filtered by specifying "FilterOn" and "FilterValue". The general rule is that you can filter on any column the API returns. Two exceptions are the media library and shared library queries. For those, you need only specify "FilterValue" and the API will look for the value in each field of the content data.
For example, to only show the media workflows called "Progressive (No Transcoding)"
| Url | {ensembleWebAppUrl}/api/MediaWorkflows?FilterOn=Name&FilterValue=Progressive%20Upload%20-%20System |
| Example | https://cloud.ensemblevideo.com/api/MediaWorkflows?FilterOn=Name&FilterValue=Progressive%20(No%20Transcoding) |
To only show the media workflows for the library called "33 Library"
| Url | {ensembleWebAppUrl}/api/MediaWorkflows?FilterOn=LibraryName&FilterValue=33%20Library |
| Example | https://cloud.ensemblevideo.com/api/MediaWorkflows?FilterOn=LibraryName&FilterValue=33%20Library |
To only show the media workflows in the library with ID "f2e41d0a-c89f-4699-9072-27c60cb731c7"
| Url | {ensembleWebAppUrl}/api/MediaWorkflows?FilterOn=LibraryID&FilterValue=f2e41d0a-c89f-4699-9072-27c60cb731c7 |
| Example | https://cloud.ensemblevideo.com/api/MediaWorkflows?FilterOn=LibraryID&FilterValue=f2e41d0a-c89f-4699-9072-27c60cb731c7 |
Paging
The paging parameters are:
| Parameter Name | Description |
|---|---|
| PageIndex | The number of the current page. Default is whatever is set in the API web.config, see Settings. |
| PageSize | The number of items to return per page. Default is whatever you set in the API web.config, see Settings. |
To display only the first page of the media workflows list with one item per page
| Url | {ensembleWebAppUrl}/api/MediaWorkflows?PageIndex=1&PageSize=1 |
| Example | https://cloud.ensemblevideo.com/api/MediaWorkflows?PageIndex=1&PageSize=1 |
Combining Filtering and Paging
To only show the media workflows for the library called "33 Library," but with only one item per page, and only the first page
| Url | {ensembleWebAppUrl}/api/MediaWorkflows?FilterOn=LibraryName&FilterValue=33%20Library&PageIndex=1&PageSize=1 |
| Example | https://cloud.ensemblevideo.com/api/MediaWorkflows?FilterOn=LibraryName&FilterValue=33%20Library&PageIndex=1&PageSize=1 |
