Office 365 Video REST API Overview

On April 16th, Office 365 Video has started moving from first release to general availability worldwide.

At the same time, a new REST API was launched and documented to be able to build your own applications (mobile, desktop, web…) on top of Office 365 Video.

Let’s get started to learn how to use this new API to perform basic operations.

Check if Office 365 Video is available and discover the API endpoint

Because Office 365 video has started to be deployed on all tenants few days ago, it’s not necessary available for your organization and/or your Office 365 administrator can disable it.

To check if the service is currently available and/or usable, you can send a request to the following URL :

https://tenant.sharepoint.com/_api/VideoService.Discover

By querying this URL, you will retrieve a response as you can see below :

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:georss="http://www.georss.org/georss" xmlns:gml="http://www.opengis.net/gml" xml:base="https://tenant.sharepoint.com/_api/">
<id>https://tenant.sharepoint.com/_api/VideoService.Discover</id>
<category term="SP.Publishing.VideoServiceDiscoverer" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
<link rel="edit" href="VideoService.Discover" />
<title />
<updated>2015-01-01T01:00:00Z</updated>
<author>
  <name />
</author>
<content type="application/xml">
  <m:properties>
    <d:ChannelUrlTemplate>https://tenant.sharepoint.com/portals/hub/_layouts/15/videochannel.aspx?channel={0}</d:ChannelUrlTemplate>
    <d:IsVideoPortalEnabled m:type="Edm.Boolean">true</d:IsVideoPortalEnabled>
    <d:PlayerUrlTemplate>https://tenant.sharepoint.com/portals/hub/_layouts/15/videoplayer.aspx?v={0}</d:PlayerUrlTemplate>
    <d:VideoPortalLayoutsUrl>https://tenant.sharepoint.com/portals/hub/_layouts/15</d:VideoPortalLayoutsUrl>
    <d:VideoPortalUrl>https://tenant.sharepoint.com/portals/hub</d:VideoPortalUrl>
  </m:properties>
</content>
</entry>

In this response, you can check if Office 365 video is available and activated (cf. IsVideoPortalEnabled).

If the service is available, you can retrieve the VideoPortalUrl which is the path used by the new REST API to get the list of channels, get a video, upload a video, etc…

Retrieve the list of available channels

In Office 365 Video, when a user wants to upload a video and share it with colleagues, the video is stored (classified) in a channel.

By default, channels are created by administrators and viewable by all the users. To retrieve the list of all available (viewable) channels, you have to query the VideoPortalUrl retrieved previously as you can see below :

https://tenant.sharepoint.com/portals/hub/_api/VideoService/Channels

By querying that URL, you will retrieve a list of channels. Each channel is described by the following structure :

<entry>
<id>https://tenant.sharepoint.com/portals/hub/_api/VideoService/Channels(guid'01234567-abcd-cded-1234-1234567890ab')</id>
<category term="SP.Publishing.VideoChannel" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
<link rel="edit" href="VideoService/Channels(guid'01234567-abcd-cded-1234-1234567890ab')" />
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Search" type="application/atom+xml;type=entry" title="Search" href="VideoService/Channels(guid'01234567-abcd-cded-1234-1234567890ab')/Search" />
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/SpotlightVideos" type="application/atom+xml;type=feed" title="SpotlightVideos" href="VideoService/Channels(guid'01234567-abcd-cded-1234-1234567890ab')/SpotlightVideos" />
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Videos" type="application/atom+xml;type=feed" title="Videos" href="VideoService/Channels(guid'01234567-abcd-cded-1234-1234567890ab')/Videos" />
<title />
<updated>2015-01-01T01:00:00Z</updated>
<author>
  <name />
</author>
<content type="application/xml">
  <m:properties>
    <d:Description />
    <d:Id m:type="Edm.Guid">01234567-abcd-cded-1234-1234567890ab</d:Id>
    <d:TileHtmlColor>#2A8DD4</d:TileHtmlColor>
    <d:Title>Community</d:Title>
    <d:YammerEnabled m:type="Edm.Boolean">true</d:YammerEnabled>
  </m:properties>
</content>
</entry>

 

If you want to retrieve the list of channels on which you are able to perform edit operations (e.g upload, update, delete), you just need to query the following URL (the structure of the response if the same as for viewable channels) :

https://tenant.sharepoint.com/portals/hub/_api/VideoService/CanEditChannels

Retrieve the list of videos for a channel

Now that you’re able to get the list of channels, you certainly want to retrieve the list of available videos for that channel.

It’s pretty simple and you just have to query that URL (replace the GUID with the appropriate value based on IDs retrieved in the list of channels) :

https://tenant.sharepoint.com/portals/hub/_api/VideoService/Channels(guid'01234567-abcd-cded-1234-1234567890ab')/Videos

By querying that URL, you will retrieve a list of videos for the selected channel. Each video is described by the following structure :

<entry>
<id>https://tenant.sharepoint.com/portals/hub/_api/VideoService/Channels(guid'01234567-abcd-cded-1234-1234567890ab')/Videos(guid'01234567-abcd-cded-1234-1234567890ab')</id>
<category term="SP.Publishing.VideoItem" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
<link rel="edit" href="VideoService/Channels(guid'01234567-abcd-cded-1234-1234567890ab')/Videos(guid'01234567-abcd-cded-1234-1234567890ab')" />
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Author" type="application/atom+xml;type=entry" title="Author" href="VideoService/Channels(guid'01234567-abcd-cded-1234-1234567890ab')/Videos(guid'01234567-abcd-cded-1234-1234567890ab')/Author" />
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Owner" type="application/atom+xml;type=entry" title="Owner" href="VideoService/Channels(guid'01234567-abcd-cded-1234-1234567890ab')/Videos(guid'01234567-abcd-cded-1234-1234567890ab')/Owner" />
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/PeopleInMedia" type="application/atom+xml;type=feed" title="PeopleInMedia" href="VideoService/Channels(guid'01234567-abcd-cded-1234-1234567890ab')/Videos(guid'01234567-abcd-cded-1234-1234567890ab')/PeopleInMedia" />
<title />
<updated>2015-01-01T01:00:00Z</updated>
<author>
  <name />
</author>
<content type="application/xml">
  <m:properties>
    <d:ChannelID m:type="Edm.Guid">01234567-abcd-cded-1234-1234567890ab</d:ChannelID>
    <d:CreatedDate m:type="Edm.DateTime">2015-01-01T01:00:00Z</d:CreatedDate>
    <d:Description />
    <d:DisplayFormUrl>https://tenant.sharepoint.com/portals/community/pVid/Forms/DispForm.aspx?ID=1</d:DisplayFormUrl>
    <d:FileName>AwesomeVideo.mp4</d:FileName>
    <d:OwnerName>Stephane Cordonnier</d:OwnerName>
    <d:ServerRelativeUrl>/portals/community/pVid/AwesomeVideo.mp4</d:ServerRelativeUrl>
    <d:ThumbnailUrl>https://tenant.sharepoint.com/portals/community/pVid/AwesomeVideo.mp4.PNG?VideoPreview=1</d:ThumbnailUrl>
    <d:Title>My Awesome Video</d:Title>
    <d:ID m:type="Edm.Guid">01234567-abcd-cded-1234-1234567890ab</d:ID>
    <d:Url>https://tenant.sharepoint.com/portals/community/pVid/AwesomeVideo.mp4</d:Url>
    <d:VideoDurationInSeconds m:type="Edm.Int32">120</d:VideoDurationInSeconds>
    <d:VideoProcessingStatus m:type="Edm.Int32">2</d:VideoProcessingStatus>
    <d:ViewCount m:type="Edm.Int32">10</d:ViewCount>
    <d:YammerObjectUrl>https://tenant.sharepoint.com/portals/hub/_layouts/15/videoplayer.aspx?v=https%3A%2F%2Ftenant%2Esharepoint%2Ecom%2Fportals%2Fcommunity%2FpVid%2FAwesomeVideo%2Emp4</d:YammerObjectUrl>
  </m:properties>
</content>
</entry>

 

As you can see above, you are able to retrieve a lot of information about the video (title, author, duration, number of views, URL…).

But if you watch the URL value, it corresponds to the physical location of the video stored in a SharePoint site (each channel is a SharePoint site collection).

If a lot of users try to access the video at the same time, it may have an impact of the performance of your tenant because SharePoint is not optimized for that kind of usage.

When a video is uploaded in a channel, it’s also sent to Azure Media Services (at no additionnal costs) to be able to use the streaming capabilities of Azure.

If you want to retrieve the corresponding URL of your video in Azure Media Services, you just need to query the following URL (replace the GUIDs for the channel and the video with appropriate values) :

https://tenant.sharepoint.com/portals/hub/_api/VideoService/Channels(guid'01234567-abcd-cded-1234-1234567890ab')/Videos(guid'01234567-abcd-cded-1234-1234567890ab')/GetPlaybackUrl(0)

At the end of the URL, you can see a value when calling the GetPlaybackUrl method. When the value is equal to zero, it indicates you want to use the HTTP Live Streaming (HLS) capability of Azure Media Services.

HLS is compatible with all devices (mobile, desktop, web…) but if you want to use another format/protocol, you can pass ‘1’ for the value, which indicates you want to use Smooth Streaming/MPEG-DASH instead of HLS. See the example below :

https://tenant.sharepoint.com/portals/hub/_api/VideoService/Channels(guid'01234567-abcd-cded-1234-1234567890ab')/Videos(guid'01234567-abcd-cded-1234-1234567890ab')/GetPlaybackUrl(1)

For security reasons, videos stored in Azure Media Services are encrypted so if you want to use Smooth Streaming/MPEG-DASH instead of HLS, you need one additionnal step (retrieve an access token) to be able to use and access the retrieved URL.

Conclusion

We’ve just give you an overview of how to access and use the new REST API available with Office 365 Video to retrieve channels and videos but many other operations are available in this API (upload videos, delete videos, update metadata…).

The new API is already used by the Office 365 Video application for iPhone : https://itunes.apple.com/app/id953685679

If you want more information on the Office 365 Video REST API, you can read the documentation on the MSDN website : https://msdn.microsoft.com/office/office365/APi/video-rest-operations.

Advertisements

One thought on “Office 365 Video REST API Overview

  1. Pingback: SharePoint 2013 & Office 365: Recopilatorio de enlaces interesantes (LXVII)! - Blog de Juan Carlos González en Geeks.MS

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s