In my last post I was talking about our vision and what steps we will make for Studio to have a powerful API. This time is going to be much more practical and is the first part of a two-episode demonstration of some practical challenges that you can overcome with the new endpoints. This first part focuses on the recently released admin data management support while the next post - coming shortly after this one - will walk you through how you can access and work with media insights via the API.
It will be longer than usual because it’s sort of a quick tutorial. But before jumping the gun, you should already have Postman on your computer and authentication done with the help of this Canvas Studio guide:
https://community.canvaslms.com/t5/Studio-Blog/Connecting-Studio-OAuth-via-Postman/ba-p/259739
If you verified the integration with the /ping request, then you are good to go!
1. Searching for a specific video across the entire instance
Searching across the entire instance was a very frequent demand in the past. A video could have been lost for you if you didn’t know the owner. And what if the owner is no longer with the institution? Admins had no tooling to track a specific media and dig up the needle in a haystack. Searching for a video was only possible within the scope of one’s Library after acting as the user.
The search endpoint is powerful and easy to use. Let’s first find all the videos ever uploaded to my instance with ‘black hole’ in its title!
Which will respond the following:
{
"media": [
{
"id": 32,
"title": "The Ultimate Guide to Black Holes",
"description": "If you want to continue thinking about black holes",
"duration": 735.0,
"created_at": "2018-07-07T09:23:03Z",
"thumbnail_url": "https://i.ytimg.com/vi/QqsLTNkzvaY/mqdefault.jpg",
"transcoding_status": "transcoding_finished",
"size": 19345031,
"owner": {
"id": 1,
"full_name": "Math Teacher",
"display_name": "Math Teacher",
"email": "math.teacher@bme.com"
}
},
{
"id": 50,
"title": "The Largest Black Hole in the Universe - Size Comparison",
"description": “This will blow you away”,
"duration": 823.218,
"created_at": "2021-09-14T11:32:06Z",
"thumbnail_url": "https://fra.nv.instructuremedia.com/api/media/m-3bzeu7S4tmKmvt3YDCj2tQLb7y6bWgqu/thumbnail?width=540&height=320",
"transcoding_status": "transcoding_finished",
"size": 804181764,
"owner": {
"id": 1,
"full_name": "Admin User",
"display_name": "Admin User",
"email": "admin.user@bme.com"
}
},
{
"id": 104,
"title": "Black Holes Explained – From Birth to Death",
"description": "Black holes. Let us talk about them.",
"duration": 356.0,
"created_at": "2022-01-27T18:07:15Z",
"thumbnail_url": "https://i.ytimg.com/vi/e-P5IFTqB98/mqdefault.jpg",
"transcoding_status": "transcoding_finished",
"size": 4341902,
"owner": {
"id": 8,
"full_name": "Mary Student",
"display_name": "Mary Student",
"email": "mary.student@bme.com"
}
},
],
"meta": {
"current_page": 1,
"last_page": 1,
"total_count": 3
}
}
As you can see in the result, the three hits are videos uploaded by three different users. There is also some essential metadata provided, for instance created_at is one that indicates the date and time when that specific video was uploaded. When we want to free up storage from one of our devices, we typically look for two things: oldest and largest files. Well, the new search endpoint will give you a hand in this.
2. Searching for old videos when freeing up Studio storage
The search endpoint can take start_date and end_date parameters and will find videos uploaded in that date range. In my case, I just provided the end_date so that the query will know that I’m looking for all black hole titled videos that were uploaded before 2019.
{
"media": [
{
"id": 32,
"title": "The Ultimate Guide to Black Holes",
"description": "If you want to continue thinking about black holes",
"duration": 735.0,
"created_at": "2018-07-07T09:23:03Z",
"thumbnail_url": "https://i.ytimg.com/vi/QqsLTNkzvaY/mqdefault.jpg",
"transcoding_status": "transcoding_finished",
"size": 19345031,
"owner": {
"id": 1,
"full_name": "Math Teacher",
"display_name": "Math Teacher",
"email": "math.teacher@bme.com"
}
}
],
"meta": {
"current_page": 1,
"last_page": 1,
"total_count": 1
}
}
Of course, you can use the date range query without specifying a title as well to find all videos uploaded before 2019, the combination is only for demonstration purposes. So what if we wanted to look for huge videos taking up significant space now?
3. Searching for large videos files
The search endpoint can take min_size and max_size parameters to find videos in that size range. Here I’ll look for all videos that take up more than 800MB by specifying only the min_ size parameter. As the documentation says, the size is specified in bytes so we need to make sure we input the right number.
{
"media": [
{
"id": 50,
"title": "The Largest Black Hole in the Universe - Size Comparison",
"description": "This will blow you away",
"duration": 823.218,
"created_at": "2021-09-14T11:32:06Z",
"thumbnail_url": "https://fra.nv.instructuremedia.com/api/media/m-3bzeu7S4tmKmvt3YDCj2tQLb7y6bWgqu/thumbnail?width=540&height=320",
"transcoding_status": "transcoding_finished",
"size": 804181764,
"owner": {
"id": 1,
"full_name": "Admin User",
"display_name": "Admin User",
"email": "admin.user@bme.com"
}
},
{
"id": 510,
"title": "Wormholes Explained – Breaking Spacetime",
"description": "Are wormholes real or are they just magic disguised as physics and maths?",
"duration": 3635,
"created_at": "2022-07-02T14:23:02Z",
"thumbnail_url": "https://i.ytimg.com/vi/QqsLTNkzvaY/mqdefault.jpg",
"transcoding_status": "transcoding_finished",
"size": 1792345031,
"owner": {
"id": 1,
"full_name": "Math Teacher",
"display_name": "Math Teacher",
"email": "math.teacher@bme.com"
}
}
],
"meta": {
"current_page": 1,
"last_page": 1,
"total_count": 2
}
}
Once you obtain the media ID for a specific video, you can accomplish quite a few things with that. Get a list of courses where it is embedded, the users who have access to it or change user permissions (edit/view) if needed to be done in an automated fashion for any reason. Feel free to wander around the media endpoints to see them. Furthermore, there is one more thing that you cannot see in the endpoints, but definitely needs mentioning!
4. Find out everything about a video (advanced)
The one-stop shop to find out all the information you can get on a video. It’s not an endpoint. It’s a script you need to execute if you really want to get all the details of a certain video, therefore the advanced tag.
- basic details: id, title, description, duration, size, created_at
- owner: the owner of the media
- collection: the collection where the media is uploaded to
- captions: list of captions the media has
- courses: list of courses where the media is embedded into
- tags: list of tags the media has
- users: list of users whom the media is shared with (either directly or indirectly) and the permission they have to the media
We created a public repository where all these powerful queries will be documented. Once you’ve set up the authentication (guide in the repo), head to the Get Media Details page and run the necessary command. The output will be provided in the same JSON format as the endpoint responses.
The last thing we want to show you is probably the most interesting addition!
5. Retain content from leaving or retiring educators
One of the most frequently asked questions is what’s the best way to move someone’s content to another user’s Library. We didn’t have a better answer today than to act as the user and share each video and collection one by one with the person who takes over those. That can be overwhelming when the user leaves behind hundreds of videos and dozens of collections, so we wanted to provide a better way for that. The transfer media endpoint looks really simple to use but needs some explanation about what really happens behind the scenes.
The first thing is obtaining these user IDs which can be queried from the search user endpoint. This will very soon include an email address in its parameter list, so that it can be used to find the exact person you are looking for. Alternatively, it is recommended to use the endpoint that lists all users that have access to a certain media. Pick a video from the owner’s library and use this endpoint with its media ID which will output the owner along with their user ID.
The second thing we need to talk about is the result of this query. According to the API documentation, you will be responded in the following structure:
Where there are IDs displayed in these lists, the query did successfully run. However, some media and collections could not be transferred to the designated user. This endpoint transfers only those media that are not shared with anyone. The rationale behind is that we want to keep Studio consistent with whom you can share content with according to the sharing rules that help us comply with FERPA. An associate physics professor might inherit a retiring professor’s classroom recordings but that person might not be enrolled in the same course as the students in those recordings. Therefore those videos could not even be shared with the new owner on the Studio UI. This means that the leftover videos and collections need to be manually moved to new owners selected by the retiring professor or someone else in the faculty.
If you tried these endpoints while you read through the post, huge kudos for you! If you browsed through I really appreciate it for taking the time because it’s probably the longest Studio post so far 🙂
Next part of this tutorial is already done and I’ll post it along with the release of the new endpoints this month. As a sneak peek, that's where you’ll be able to get media insights for all your videos in a course with just one click..
Hope you are excited!
Akos
The content in this blog is over six months old, and the comments are closed. For the most recent product updates and discussions, you're encouraged to explore newer posts from Instructure's Product Managers.