...
| Note |
|---|
| The user should not be able to manipulate their playback session count themselves; You should not provide the user with a direct means to access the API but rather call it as a side-effect of other user initiated actions. |
Showing a list of playback sessions
The client can call the GET method on the resource index to obtain a list of sessions that are currently registered.
This may be useful if the user has been denied starting a new playback session and wants to know which devices are currently watching.
| Tip |
|---|
| It is not possible for Amino to terminate a media playback session and the user will need to stop playback on the device. |
Creating a new session
The client should retrieve an index of the current sessions so that it is able to tell the user whether she can start a new stream or not.
...
When the client calls the API to create a new session the server will check the number of sessions that already exist.
The server will respond with the details of the session that has been opened. The client should store the id of the entity so that it can make future calls that reference it.
If the account is not allowed to play another stream then the API will respond with a "403 Forbidden" error, with a body as below:
...
Therefore, it is essential that the client calls PATCH in order to prevent the server from incorrectly assuming the session is no longer active.
Deleting a session when the user stops watching
The client is expected to call the DELETE method on the resource when the user stops watching the media.
We expect that clients will not give users the ability to delete a session without stopping playback.
We realize that it is not always possible for the client to call this endpoint; For example the client could switch off the device or there could be a physical failure in the network.
The server will regularly check for sessions that have not been updated and delete them automatically.
Example flow
| Description | URL | Number of MediaPlaySessions after call is made |
|---|---|---|
| User account is not watching anything | 0 | |
| User starts watching something on their set top box | POST /users/{user_id}/media_play_sessions | 1 |
| Another person in the household starts watching something on a their mobile | POST /users/{user_id}/media_play_sessions | 2 |
| Each device periodically tells the server that the session is still active | PATCH /media_play_sessions/{media_play_session_id} | 2 |
| The second user presses stop on their mobile device | 2 | |
| The first user switches off the set top box without giving the client a chance to delete their session | DELETE /media_play_sessions/{media_play_session_id} | 1 (zombie session) |
| Some time later the periodic clean up job runs on the server and deletes the zombie session | 0 |