Add playlists API service endpoint (#17)

* Add playlists API service endpoint * Unit test: check if configured opencast supports playlists api The playlists api is supported since api version v1.11.0 --------- Co-authored-by: Dennis Benz <dennis.benz@uos.de>
elan-ev · Apr 24, 2024 · 361348d · 361348d
1 parent 6bf9c46
commit 361348d
Show file tree

Hide file tree

Showing 8 changed files with 522 additions and 1 deletion.
diff --git a/src/OpencastApi/Mock/OcMockHanlder.php b/src/OpencastApi/Mock/OcMockHanlder.php
@@ -50,7 +50,7 @@ public static function getHandlerStackWithPath($data, $recordFilePath = null)
             ];
             $response = new Response($status, $headers, $body, $version, json_encode($reasonData));
 
-            if ($method === 'PUT' && !empty($requestBody)) {
+            if (in_array($method, ['POST', 'PUT']) && !empty($requestBody)) {
                 $requestBody = urldecode($requestBody);
             }
             foreach ($data as $resPath => $resData) {

diff --git a/src/OpencastApi/Opencast.php b/src/OpencastApi/Opencast.php
@@ -33,6 +33,9 @@ class Opencast
     /** @var \OpencastApi\Rest\OcGroupsApi $groupsApi */
     public $groupsApi;
 
+    /** @var \OpencastApi\Rest\OcPlaylistsApi $playlistsApi */
+    public $playlistsApi;
+
     /** @var \OpencastApi\Rest\OcRecordings $recordings */
     public $recordings;
 

diff --git a/src/OpencastApi/Rest/OcPlaylistsApi.php b/src/OpencastApi/Rest/OcPlaylistsApi.php
@@ -0,0 +1,159 @@
+<?php
+namespace OpencastApi\Rest;
+
+class OcPlaylistsApi extends OcRest
+{
+    const URI = '/api/playlists';
+
+    public function __construct($restClient)
+    {
+        // The Playlist API is available since API version 1.11.0.
+        parent::__construct($restClient);
+    }
+
+    ## [Section 1]: General API endpoints.
+
+    /**
+     * Get playlists.
+     * Playlists that you do not have read access to will not show up.
+     *
+     * @param array $params (optional) The list of query params to pass which can contain the followings:
+     * [
+     *      'limit' => (int) {The maximum number of results to return for a single request},
+     *      'offset' => (int) {The index of the first result to return},
+     *      'sort' => {The sort criteria. A criteria is specified by a case-sensitive sort name and the order separated by a colon (e.g. updated:ASC). Supported sort names: 'updated'. Use the order ASC to sort ascending or DESC to sort descending.}
+     * ]
+     *
+     * @return array the response result ['code' => 200, 'body' => '{A (potentially empty) list of playlists}']
+     */
+    public function getAll($params = [])
+    {
+        $uri = self::URI;
+
+        $query = [];
+
+        if (array_key_exists('limit', $params) && !empty($params['limit'])) {
+            $query['limit'] = $params['limit'];
+        }
+        if (array_key_exists('offset', $params) && !empty($params['offset'])) {
+            $query['offset'] = $params['offset'];
+        }
+
+        $supportedSortNames = ['updated'];
+        $supportedSorts= [];
+        foreach ($supportedSortNames as $sortName) {
+            $supportedSorts[] = "$sortName:ASC";
+            $supportedSorts[] = "$sortName:DESC";
+        }
+
+        if (array_key_exists('sort', $params) && !empty($params['sort']) &&
+            in_array($params['sort'], $supportedSorts)) {
+            $query['sort'] = $params['sort'];
+        }
+
+        $options = $this->restClient->getQueryParams($query);
+        return $this->restClient->performGet($uri, $options);
+    }
+
+    /**
+     * Get a playlist.
+     *
+     * @param string $playlistId the identifier of the playlist
+     *
+     * @return array the response result ['code' => 200, 'body' => '{The playlist (object)}']
+     */
+    public function get($playlistId)
+    {
+        $uri = self::URI . "/{$playlistId}";
+        return $this->restClient->performGet($uri);
+    }
+
+    /**
+     * Creates a playlist.
+     *
+     * @param string|array $playlist A playlist
+     *
+     * @return array the response result ['code' => 201, 'body' => '{The new playlist (object)}']
+     */
+    public function create($playlist)
+    {
+        $formData = [
+            'playlist' => $playlist,
+        ];
+
+        $options = $this->restClient->getFormParams($formData);
+        return $this->restClient->performPost(self::URI, $options);
+    }
+
+    /**
+     * Updates a playlist.
+     *
+     * @param string $playlistId the identifier of the playlist
+     * @param string|array $playlist the updated playlist
+     *
+     * @return array the response result ['code' => 200, 'body' => '{The updated playlist (object)}']
+     */
+    public function update($playlistId, $playlist)
+    {
+        $uri = self::URI . "/{$playlistId}";
+
+        $formData = [
+            'playlist' => $playlist,
+        ];
+
+        $options = $this->restClient->getFormParams($formData);
+        return $this->restClient->performPut($uri, $options);
+    }
+
+    /**
+     * Removes a playlist.
+     *
+     * @param string $playlistId the identifier of the playlist
+     *
+     * @return array the response result ['code' => 200, 'body' => '{The removed playlist (object)}']
+     */
+    public function delete($playlistId)
+    {
+        $uri = self::URI . "/{$playlistId}";
+        return $this->restClient->performDelete($uri);
+    }
+
+    ## End of [Section 1]: General API endpoints.
+
+    ## [Section 2]: Entries.
+
+    /**
+     * Updates the entries of a playlist
+     *
+     * @param string $playlistId the identifier of the playlist
+     * @param string|array $playlistEntries the playlist entries
+     *
+     * @return array the response result ['code' => 200, 'body' => '{The updated playlist (object)}']
+     */
+    public function updateEntries($playlistId, $playlistEntries)
+    {
+        $uri = self::URI . "/{$playlistId}/entries";
+
+        $formData = [
+            'playlistEntries' => $playlistEntries,
+        ];
+
+        $options = $this->restClient->getFormParams($formData);
+        return $this->restClient->performPost($uri, $options);
+    }
+
+    /**
+     * Removes all entries of the playlist
+     *
+     * @param string $playlistId the identifier of the playlist
+     *
+     * @return array the response result ['code' => 200, 'body' => '{The updated playlist (object)}']
+     */
+    public function emptyEntries($playlistId)
+    {
+        return $this->updateEntries($playlistId, []);
+    }
+
+    ## End of [Section 2]: Entries.
+}
+?>
diff --git a/src/OpencastApi/Rest/OcRest.php b/src/OpencastApi/Rest/OcRest.php
@@ -2,6 +2,7 @@
 namespace OpencastApi\Rest;
 
 abstract class OcRest {
+    /** @var OcRestClient */
     protected $restClient;
 
     public function __construct($restClient)

diff --git a/tests/DataProvider/PlaylistsDataProvider.php b/tests/DataProvider/PlaylistsDataProvider.php
@@ -0,0 +1,26 @@
+<?php
+namespace Tests\DataProvider;
+
+class PlaylistsDataProvider {
+
+    public static function getAllCases(): array
+    {
+        return [
+            [[]],
+            [['sort' => 'updated:DESC']],
+            [['limit' => 2]],
+            [['offset' => 1]],
+        ];
+    }
+
+    public static function getPlaylist()
+    {
+        return '{"title":"Opencast Playlist","description":"PHP UNIT TEST_' . strtotime('now') . '_{update_replace}","creator":"Opencast","entries":[{"contentId":"ID-about-opencast","type":"EVENT"}],"accessControlEntries":[{"allow":true,"role":"ROLE_USER_BOB","action":"read"}]}';
+    }
+
+    public static function getEntries()
+    {
+        return '[{"contentId":"ID-about-opencast","type":"EVENT"},{"contentId":"ID-3d-print","type":"EVENT"}]';
+    }
+}
+?>
diff --git a/tests/DataProvider/mock_responses/api_playlists.json b/tests/DataProvider/mock_responses/api_playlists.json
@@ -0,0 +1,59 @@
+{
+    "/api/playlists": {
+        "GET": [
+            {
+                "body": "[{\"entries\":[{\"contentId\":\"ID-about-opencast\",\"id\":\"ID-entry-opencast\",\"type\":\"EVENT\"},{\"contentId\":\"ID-3d-print\",\"id\":\"ID-entry-print\",\"type\":\"EVENT\"}],\"creator\":\"Opencast\",\"description\":\"This is a playlist about Opencast\",\"id\":\"ID-opencast-playlist\",\"title\":\"Opencast Playlist\",\"updated\":\"2024-02-14T08:56:40Z\",\"accessControlEntries\":[{\"allow\":true,\"role\":\"ROLE_USER_BOB\",\"action\":\"read\"}]},{\"entries\":[{\"contentId\":\"ID-about-opencast\",\"id\":\"ID-about-opencast\",\"type\":\"EVENT\"}],\"creator\":\"Opencast\",\"description\":\"This is a playlist about Opencast\",\"id\":\"ID-another-opencast-playlist\",\"title\":\"Another Opencast Playlist\",\"updated\":\"2024-03-05T15:10:55Z\",\"accessControlEntries\":[{\"allow\":true,\"role\":\"ROLE_USER_BOB\",\"action\":\"read\"}]}]",
+                "params": "",
+                "status": 200
+            }
+        ],
+        "POST": [
+            {
+                "body": "{\"entries\":[{\"contentId\":\"ID-about-opencast\",\"id\":\"ID-entry-opencast\",\"type\":\"EVENT\"}],\"creator\":\"Opencast\",\"description\":\"This is a playlist about Opencast\",\"id\":\"ID-opencast-playlist\",\"title\":\"Opencast Playlist\",\"updated\":\"2024-03-05T15:10:55Z\",\"accessControlEntries\":[{\"allow\":true,\"role\":\"ROLE_USER_BOB\",\"action\":\"read\"}]}",
+                "params": "",
+                "status": 201
+            }
+        ]
+    },
+    "/api/playlists/ID-opencast-playlist": {
+        "GET": [
+            {
+                "body": "{\"entries\":[{\"contentId\":\"ID-about-opencast\",\"id\":\"ID-entry-opencast\",\"type\":\"EVENT\"}],\"creator\":\"Opencast\",\"description\":\"This is a playlist about Opencast\",\"id\":\"ID-opencast-playlist\",\"title\":\"Opencast Playlist\",\"updated\":\"2024-03-05T15:10:55Z\",\"accessControlEntries\":[{\"allow\":true,\"role\":\"ROLE_USER_BOB\",\"action\":\"read\"}]}",
+                "params": "",
+                "status": 200
+            }
+        ],
+        "PUT": [
+            {
+                "body": "{\"entries\":[{\"contentId\":\"ID-about-opencast\",\"id\":\"ID-entry-opencast\",\"type\":\"EVENT\"}],\"creator\":\"Opencast\",\"description\":\"This is a playlist about Opencast\",\"id\":\"ID-opencast-playlist\",\"title\":\"Opencast Playlist\",\"updated\":\"2024-03-05T15:10:55Z\",\"accessControlEntries\":[{\"allow\":true,\"role\":\"ROLE_USER_BOB\",\"action\":\"read\"}]}",
+                "params": "",
+                "status": 200
+            }
+        ],
+        "DELETE": [
+            {
+                "body": "{\"entries\":[{\"contentId\":\"ID-about-opencast\",\"id\":\"ID-entry-opencast\",\"type\":\"EVENT\"}],\"creator\":\"Opencast\",\"description\":\"This is a playlist about Opencast\",\"id\":\"ID-opencast-playlist\",\"title\":\"Opencast Playlist\",\"updated\":\"2024-03-05T15:10:55Z\",\"accessControlEntries\":[{\"allow\":true,\"role\":\"ROLE_USER_BOB\",\"action\":\"read\"}]}",
+                "params": "",
+                "status": 200
+            }
+        ]
+    },
+    "/api/playlists/ID-opencast-playlist/entries": {
+        "POST": [
+            {
+                "body": "{\"entries\":[],\"creator\":\"Opencast\",\"description\":\"This is a playlist about Opencast\",\"id\":\"ID-opencast-playlist\",\"title\":\"Opencast Playlist\",\"updated\":\"2024-03-05T15:10:55Z\",\"accessControlEntries\":[{\"allow\":true,\"role\":\"ROLE_USER_BOB\",\"action\":\"read\"}]}",
+                "params": {
+                    "unique_request_identifier": "playlistEntries=[]"
+                },
+                "status": 200
+            },
+            {
+                "body": "{\"entries\":[{\"contentId\":\"ID-about-opencast\",\"id\":ID-entry-opencast,\"type\":\"EVENT\"}],\"creator\":\"Opencast\",\"description\":\"This is a playlist about Opencast\",\"id\":\"ID-opencast-playlist\",\"title\":\"Opencast Playlist\",\"updated\":\"2024-03-05T15:10:55Z\",\"accessControlEntries\":[{\"allow\":true,\"role\":\"ROLE_USER_BOB\",\"action\":\"read\"}]}",
+                "params": {
+                    "unique_request_identifier": "\"type\":\"EVENT\""
+                },
+                "status": 200
+            }
+        ]
+    }
+}