API v2

From Wiki
Jump to: navigation, search

Contents

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.
Email 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

Versions prior to 4.1.0
Url {ensembleWebAppUrl}/api/content
Example https://cloud.ensemblevideo.com/api/content
4.1.0+
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

Versions prior to 4.1.0
Url {ensembleWebAppUrl}/api/content/{libraryId}
Example https://cloud.ensemblevideo.com/api/content/f2e41d0a-c89f-4699-9072-27c60cb731c7
4.1.0+
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.


Shared Library

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

Versions prior to 4.1.0
Url {ensembleWebAppUrl}/api/sharedcontent
Example https://cloud.ensemblevideo.com/api/sharedcontent
4.1.0+
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

Versions prior to 4.1.0
Url {ensembleWebAppUrl}/api/sharedcontent/{libraryId}
Example https://cloud.ensemblevideo.com/api/sharedcontent/f2e41d0a-c89f-4699-9072-27c60cb731c7
4.1.0+
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