The Xbox One shell will provide a gallery experience where users can view their own and their friends’ videos, with pivots on pinned to profile and recent.
The RESTful APIs offer lots of flexibility for custom experiences inside titles, companion applications on Xbox One, and companion applications on SmartGlass.
The Game Clips Metadata Service requires the following claims:
The Game Clips Metadata Service will only enumerate and return videos to a user that he has permission to see. Consequently, the service will check to be sure:
All of this work is behind the scenes; when the list of videos is returned to the caller, the caller can expect to display any or all of them in the list without further filtering.
Use this API to retrieve the user’s videos stored in the cloud. Note that if you want to combine cloud-stored videos with local videos that haven’t been pushed up yet, use the ApplicationClipQuery API.
Developers can request all videos based on a user’s XUID, or based on the combination of XUID and SCID. The results are paged, and can be sorted by most viewed or top rated. The default sort is most recent.
A GameClip object contains all of the relevant metadata for a video. The response will be a list of GameClip objects in a QueryClipsResponse object.
When a service error is encountered, an appropriate HTTP error code will be returned. Optionally, the service may also include a ServiceErrorResponse object.
All objects are in JSON format.
The GameClipThumbnail object contains the information related to an individual thumbnail. There can be multiple sizes per clip and it is up to the client to select the proper one for display.
The GameClipUri object contains the information related to an instance of a game clip video asset. Since there can be multiple representations for a clip, it is up to the client to select the most appropriate one for playback.
The QueryClipsResponse object wraps the list of return game clips along with paging information for the list. It is comprised of an array of GameClip objects and a PagingInfo object.
The PagingInfo object contains two fields that are used for subsequent calls to get additional results.
The process to get a user’s friend’s videos is exactly the same as getting the owner’s own videos, with the friend’s XUID used as “ownerId” in the URI. There is no batch API to input many XUIDs at once; the guidance is to call the API for each friend individually.
Titles have a string that’s stored with the rest of a video’s metadata that they can use for whatever they want. They have the option of creating this metadata when the clip is created, or adding it later on (for example, when the clip is enumerated or watched).
A title can only update the “titleData” metadata for a SCID to which it has access. This is enforced through Content Isolation.
URI
/users/me/scids/{scid}/clips/{gameClipId}
to update clip metadata for the specific clip
HTTP Method
POST
The following table lists the resource identifiers.
| Name | Description | Required? | Data Type | Max Size |
|---|---|---|---|---|
| scId | Service configuration ID of the resource being accessed. | Required | String | 50 |
| gameClipId | GameClip ID of the resource that is being accessed. | Required | String | 50 |
The body of the request should be a MetadataUpdateRequest object in JSON format.
The MetadataUpdateRequest object contains all the metadata that should be updated for a clip. All fields are optional and if not specified, will not be updated. If a field is included, it will be updated to the value specified, if not included it will not be updated. Sending null or default values for a field will cause it to be set to null or default. To update the title’s properties, just send the following in the JSON:
| Field | Type | Description |
|---|---|---|
| titleData | string | The title-specific property bag. |
The “Views” field is public—meaning, all authenticated callers to the Game Clips Metadata Service may update views.
URI
/users/{ownerId}/scids/{scid}/clips/{gameClipId}/views
HTTP Method
POST
Resource Identifiers are shown in the following table.
| Name | Description | Required? | Data Type | Max Size |
|---|---|---|---|---|
| scId | Service configuration ID of the resource being accessed. | Required | String | 50 |
| gameClipId | GameClip ID of the resource that is being accessed. | Required | String | 50 |
Request
There is no body for this request.
Response
Upon successful update of the metadata an HTTP Status code of 200 will be returned. Otherwise a ServiceErrorResponse object in JSON format will be returned with an appropriate HTTP Status Code.
This is another public field in the video metadata. When the URI is called, the rating is applied to the specified clip. Rating is an average of all ratings for all time. The rating value sent must be a double between 0.0 – 1.0. (for example, for a 5 point scale 1 = .2, 2 = .4, 3 = .6, 4 = .8, 5 = 1.0).
URI
/users/{ownerId}/scids/{scid}/clips/{gameClipId}/ratings/{rating value}
HTTP Method
POST
The following table lists the resource identifiers.
| Name | Description | Required? | Data Type | Max Size |
|---|---|---|---|---|
| scId | Service configuration ID of the resource being accessed. | Required | String | 50 |
| gameClipId | GameClip ID of the resource that is being accessed. | Required | String | 50 |
Request
There is no body for this request.
Response
Upon successful update of the metadata an HTTP Status code of 200 will be returned. Otherwise a ServiceErrorResponse object in JSON format will be returned with an appropriate HTTP Status Code.