Browsing Containers for Media
Objective
To teach you which calls are necessary to navigate hierarchical container structures from the top down to a single media object.
Requirements
  • A properly configured hierarchical container structure
  • A client authenticated as a user with the SyncTV service
APIs Covered
SyncTV provides a robust and highly flexible system for organizing media into a catalog. This is done through containers, which function similarly to folders in a traditional computer. Containers may contain any number of media objects or other containers.
Step 1
Retrieving the Root Containers
All containers have a parent container ID except root containers. Root containers are useful because you can query specifically for them. This allows a client application to rapidly deliver an easy to understand media catalog to the end user.

To retrieve a list of all root containers, you must perform a GET request on the container roots API as demonstrated below.
    [GET]https://service_name.synctv.com/api/v2/containers/roots.json?access_id=3645&signature=b6d0c3f3b6e4416d48f9432264a75f2a
Example Response
{
	"response": {
		"containers": [(1)
			{
			"id": 3197,
			"name": "lucas",
			"description": "3",
			"parent_id": null,
			"order_number": 1,
			"active": false,
			"leaf": false,
			"container_type": {
				"id": 1,
				"name": "WhatsOn"
			},
			-
			"meta_data": [(0)],
				"created_at": "2012-08-03T14:10:55Z",
				"updated_at": "2012-08-08T21:03:04Z",
				"images": [(0)],
				"external_id": "3",
				"published_at": "1930-01-01T00:00:00Z"
			},
			-
		],
		-
		"code": 1,
		"messages": [(1)
			"Successfully completed."
		]
		-
	}
	-
}
							
This response contains the id of the container, as well as its name, description and parent id. Notice the parent id is null, this indicates that it is a root container. For a full description of all attributes in this response, please visit the Containers API documentation.
Step 2
Retrieving Containers within a Container
Finding out what is in a container requires two calls because a container can hold both media and other containers. To figure out what containers are within a specific container you will have to perform a GET request with the container ID on the containers API as demonstrated below.
    [GET]https://service_name.synctv.com/api/v2/containers/3197/containers.json?access_id=3645&signature=b6d0c3f3b6e4416d48f9432264a75f2a
Example Response
{
	"response": {
		"containers": [(2)
			{
				"id": 3201,
				"name": "Featured",
				"description": "Sales, Gimmiks and other promotions",
				"parent_id": 3197,
				"order_number": 0,
				"active": false,
				"leaf": false,
				"container_type": {
					"id": 1,
					"name": "WhatsOn"
				},
				-
				"meta_data": [(0)],
				"created_at": "2012-08-07T18:36:43Z",
				"updated_at": "2012-08-07T18:45:50Z",
				"images": [(0)],
				"external_id": null,
				"published_at": null
			},
			-
			{
				"id": 3198,
				"name": "Genre",
				"description": "View my Genres!",
				"parent_id": 3197,
				"order_number": 0,
				"active": false,
				"leaf": false,
				"container_type": {
					"id": 5,
					"name": "Genre"
				},
				-
				"meta_data": [(0)],
				"created_at": "2012-08-07T18:29:53Z",
				"updated_at": "2012-08-07T18:59:30Z",
				"images": [(0)],
				"external_id": null,
				"published_at": null
			}
			-
		],
		-
		"code": 1,
		"messages": [(1)
			"Successfully completed."
		]
		-
	}
	-
}
							
This response contains the ids of the containers within 3197, as well as their names, descriptions and parent ids. Notice the parent id is 3197 and as such this is not a root container, but a child container of 3197. For a full description of the other attributes in this response, please visit the Containers API documentation.
Step 3
Retrieving Media in a Container
To retrieve media from a specific container you must perform a GET request with the container ID on the containers media API as demonstrated below.
    [GET]https://service_name.synctv.com/api/v2/containers/3201/media.json?access_id=3645&signature=b6d0c3f3b6e4416d48f9432264a75f2a
Example Response
{
	"response": {
		"medias": [(2)
			{
				"id": 80,
				"name": "The Matrix",
				"description": "",
				"active": false,
				"order_number": null,
				"audio_languages": [(0)],
				"duration": 0,
				"hd": false,
				"media_type": {
					"id": 1,
					"name": "Movie"
				},
				-
				"meta_data": [(0)],
				"available_at": null,
				"expires_at": null,
				"created_at": "2012-05-16T14:17:37Z",
				"updated_at": "2012-08-15T21:38:52Z",
				"images": [(0)],
				"external_id": "",
				"published_at": null,
				"avg_rating": null
			},
			-
			{
				"id": 79,
				"name": "Annie Hall",
				"description": "",
				"active": false,
				"order_number": null,
				"audio_languages": [(0)],
				"duration": 0,
				"hd": false,
				"media_type": {
					"id": 1,
					"name": "Movie"
				},
				-
				"meta_data": [(0)],
				"available_at": null,
				"expires_at": null,
				"created_at": "2012-05-16T14:17:37Z",
				"updated_at": "2012-08-15T21:57:23Z",
				"images": [(0)],
				"external_id": "",
				"published_at": null,
				"avg_rating": null
			}
			-
		],
		-
		"code": 1,
		"messages": [(1)
			"Successfully completed."
		]
		-
	}
	-
}
							
This response contains a list of all the media objects within this container. By using both this query and the query demonstrated in step two it is possible to determine the full contents of a container. For a full description of the attributes in this response, please visit the Media API documentation.
Step 4
Retrieving Details for a Specific Media
In step three we demonstrated how to pull a list of media objects within a specific container. Below we demonstrate how to retrieve details for a single media object by performing a GET request with the media ID against the media API.
    [GET]https://service_name.synctv.com/api/v2/media/80.json?access_id=3645&signature=b6d0c3f3b6e4416d48f9432264a75f2a
Example Response
{
	"response": {
		"media": {
			"id": 80,
			"name": "The Matrix",
			"description": "",
			"active": false,
			"order_number": null,
			"audio_languages": [(0)],
			"duration": 0,
			"hd": false,
			"media_type": {
				"id": 1,
				"name": "Movie"
			},
			-
			"meta_data": [(0)],
			"available_at": null,
			"expires_at": null,
			"created_at": "2012-05-16T14:17:37Z",
			"updated_at": "2012-08-15T21:38:52Z",
			"images": [(0)],
			"external_id": "",
			"published_at": null,
			"avg_rating": null
		},
		-
		"container_ids": [(3)
			3199,
			3201,
			3202
		],
		-
		"contributors": [(0)],
		"ownership_policy_ids": [(0)],
		"code": 1,
		"messages": [(1)
			"Successfully completed."
		]
		-
	}
	-
}
							
This response returns the full details of the media object with ID 80. In this case a movie titled The Matrix. You'll notice that it has multiple container IDs, media can be associated with multiple containers at once. In this case it is in both container 3201 (Featured) and 3202 (Films) a child container of 3201.