Music Server backend API

MServer

MServer (придумайте оригинальное название, пожалуйста (: ) - сервер, который предоставляет услуги редактирования/создания плэйлистов, загрузки музыки и дальнейшего прослушивания.

API

MServer является backend приложением, то есть, приложением, которое не имеет пользовательской части. Вы можете принять участие в её разработке, для этого необходимо рассмотреть API интерфейс MServer'а.

Общение между MServer и вашим будущим приложением должно происходить по протоколу HTTP(S). Content-Type должен быть: application/json.

MServer разделяет доступ, а это значит, что для работы с музыкой необходимо произвести авторизацию или регистрацию с последующей авторизацией.

Регистрация пользователя

Для регистрации пользователя необходимо отправить запрос:

POST		/api/register

И передать в теле запроса JSON:

{
    "username": "Логин пользователя",
    "password": "Пароль пользователя",
    "name": "Имя пользователя",
    "lastname": "Фамилия пользователя"
}

В ответ вы получите один из следующих HTTP кодов:

Код	HTTP описание	Описание
409	Conflict	Пользователь с таким `username` уже зарегистрирован в системе. Необходимо указать другой `username`.
201	Created	Пользователь успешно создан.
400	Bad request	Один или несколько параметров не задано.
403	Forbidden	Регистрация временно приостановлена администратором.

Данный запрос возвращает пустое тело.

Авторизация пользователя

Если Ваш пользователь зарегистрирован в системе - имеет смысл пройти авторизацию. Авторизация происходит с помощью передачи логина и пароля. В случае успешной авторизации вы получите JWT токен, который необходимо передавать в заголовке к каждому запросу.

Для авторизации необходимо послать запрос:

POST		/api/authenticate

И передать в теле запроса следующий JSON:

{
    "username": "Имя пользователя",
    "password": "Пароль пользователя"
}

Параметр	Описание
username	Логин
password	Пароль

Коды ответа:

Код	HTTP описание	Описание
401	Unauthorized	Авторизация не удалась, неверный логин/пароль.
200	OK	Авторизация прошла успешно.
400	Bad request	Один или несколько параметров не задано.

В случае успешной авторизации необходимо получить токен из тела ответа. Тело успешного ответа выглядит следующим образом:

{
    "token": "<USER_TOKEN>"
}

Данный токен необходимо передавать в каждый последующий запрос в HTTP заголовке:

Authorization: Bearer <USER_TOKEN>

Обратите внимание, что слово Bearer перед началом токена является обязательным!

В случае, если вы забудете передать токен в HTTP заголовке, или передадите невалидный токен, то получите ошибку 401 (Unauthorized).

Время жизни JWT токена: 1 час. После истечения данного времени вам потребуется отправить запрос на авторизацию снова (в фоне) и продолжить работу с новым JWT токеном. Позже мы обсудим это более детально.

Плэйлисты

Пользователь имеет право создавать плэйлисты, редактировать, удалять и просматривать плэйлисты других пользователей (если они не приватные). С точки зрения API плэйлист выглядит следующим образом:

{
   "id": "b652f29d-06f1-455e-b3f5-7cfc2e9afaa4",
   "name": "Мой плэйлист",
   "description": "Плэйлист с музыкой моего детства",
   "createDate": "2019-10-17T15:00:33.236+0000",
   "internal": true
}

Имя параметра	Тип данных	Описание
`id`	`string`	Уникальный идентификатор плэйлиста
`name`	`string`	Имя плэйлиста
`description`	`string`	Описание плэйлиста
`createDate`	`Date`	Дата создания плэйлиста
`internal`	`boolean`	Приватный плэйлист?

Создание плэйлиста

Для создания нового плэйлиста нужно отправить запрос:

POST		/api/playlist

Со следующим JSON содержимым:

{
    "name": "<ИМЯ СОЗДАВАЕМОГО ПЛЭЙЛИСТА>",
    "description": "<ОПИСАНИЕ СОЗДАВАЕМОГО ПЛЭЙЛИСТА>",
    "internal": "<ПРИВАТНЫЙ ПЛЭЙЛИСТ?>"
}

В случае успешного создания плэйлиста - вы получите JSON ответ, содержащий полное описание плэйлиста.

Коды ответа:

Код	HTTP описание	Описание
401	Unauthorized	JWT токен неверен или истёкло его время действия.
200	OK	Плэйлист создан успешно.
400	Bad request	Один или несколько параметров не задано.

Получение информации об плэйлисте

GET		/api/playlist/{id}

{id} необходимо заменить на уникальный идентификатор требуемого плэйлиста.

Ответ: JSON описание плэйлиста.

Коды ответа:

Код	HTTP описание	Описание
401	Unauthorized	JWT токен неверен или истёкло его время действия.
200	OK	Запрос успешно выполнен.
404	Not Found	Плэйлист не найден или является `internal` плэйлистом другого пользователя.

Получить свои плэйлисты

Если необходимо получить список своих плэйлистов, необходимо послать запрос:

GET		/api/playlists

Ответ: JSON-массив плэйлистов пользователя. JSON представление ответа:

{
    "content": [
        {
            "id": "c1ac227d-7075-48fc-b5f9-c99667ff884e",
            "name": "Первый плэйлист",
            "description": "Первый плэйлист как первая любовь!",
            "createDate": "2019-10-17T15:50:34.475+0000",
            "internal": false
        },
        {
	        ...
        }
    ]
}

В массиве content находятся JSON описание плэйлистов.

Код	HTTP описание	Описание
401	Unauthorized	JWT токен неверен или истёкло его время действия.
200	OK	Запрос успешно выполнен.

Получить плэйлисты пользователя

Если необходимо получить список плэйлистов интересующего пользователя, необходимо послать запрос:

GET		/api/user/{username}/playlists

Ответ: JSON-массив плэйлистов пользователя.

Внимание: Если указывать собственное (текущее) имя пользователя в {username}, то возвращаются internal и не internal плэйлисты, а если запрашиваются плэйлисты другого пользователя, то возвращаются только не internal плэйлисты.

JSON представление ответа:

{
    "content": [
        {
            "id": "c1ac227d-7075-48fc-b5f9-c99667ff884e",
            "name": "Первый плэйлист",
            "description": "Первый плэйлист как первая любовь!",
            "createDate": "2019-10-17T15:50:34.475+0000",
            "internal": false
        },
        {
	        ...
        }
    ]
}

В массиве content находятся JSON описание плэйлистов.

Код	HTTP описание	Описание
401	Unauthorized	JWT токен неверен или истёкло его время действия.
200	OK	Запрос успешно выполнен.
404	Not Found	Плэйлист не найден, либо является `internal` плэйлистом другого пользователя.

Обновление плэйлиста

Обновление плэйлиста очень похоже на создание плэйлиста. Для обновления плэйлиста нужно отправить запрос:

PUT		/api/playlist/{id}

Со следующим JSON содержимым:

{
    "name": "<НОВОЕ ИМЯ ПЛЭЙЛИСТА>",
    "description": "<НОВОЕ ОПИСАНИЕ ПЛЭЙЛИСТА>"
    "internal": "<ПРИВАТНЫЙ ПЛЭЙЛИСТ?>"
}

В случае успешного редактирования плэйлиста - вы получите JSON ответ, содержащий полное описание плэйлиста.

Коды ответа:

Код	HTTP описание	Описание
401	Unauthorized	JWT токен неверен или истёкло его время действия.
200	OK	Плэйлист отредактирован успешно.
404	Not Found	Альбом с таким ID не найден, либо является плэйлистом другого пользователя.
400	Bad request	Один или несколько параметров не задано.

Удаление плэйлиста

Для удаления плэйлиста необходимо отправить запрос:

DELETE		/api/playlist/{id}

Ответ не содержит тела. Коды ответа:

Код	HTTP описание	Описание
401	Unauthorized	JWT токен неверен или истёкло его время действия.
200	OK	Плэйлист удалён успешно.
404	Not Found	Плэйлисты с таким ID не найден, либо является плэйлистом другого пользователя.

Аудиозаписи

Пользователь имеет право загружать аудиозаписи, редактировать и удалять их. С точки зрения API аудиозапись выглядит следующим образом:

{
   "id": "b652f29d-06f1-455e-b3f5-7cfc2e9afaa4",
   "playlistId": "c1ac227d-7075-48fc-b5f9-c99667ff884e",
   "title": "Название аудиозаписи",
   "artist": "Исполнитель",
   "uploadDate": "2019-10-17T15:00:33.236+0000",
}

Имя параметра	Тип данных	Описание
`id`	`string`	Уникальный идентификатор аудиозаписи
`playlistId`	`string`	Идентификатор плэйлиста, в котором находится аудиозапись
`title`	`string`	Название аудиозаписи
`artist`	`string`	Исполнитель
`uploadDate`	`Date`	Дата загрузки аудиозаписи

Загрузка аудиозаписи в плэйлист

Для загрузки аудиозаписи необходимо отправить запрос multipart/form-data запрос:

POST		/api/playlist/{playlistId}/song

Со следующими параметрами в теле запроса:

Имя параметра	Тип данных	Описание
`audio`	`File`	.mp3 файл с content-type: `audio/mp3`
`body`	`JSON`	JSON представление аудиозаписи (поля `artist` и `title`)

Пример необходимого запроса (Chrome Request Payload):

------WebKitFormBoundarym5eIWYWg1120zYQb
Content-Disposition: form-data; name="audio"; filename="093-Starbound.mp3"
Content-Type: audio/mp3


------WebKitFormBoundarym5eIWYWg1120zYQb
Content-Disposition: form-data; name="body"; filename="blob"
Content-Type: application/json

{"artist":"Open Source","title":"Starbound"}
------WebKitFormBoundarym5eIWYWg1120zYQb--

В случае успешной загрузки аудиозаписи - вы получите JSON ответ, содержащий полное описание аудиозаписи.

Коды ответа:

Код	HTTP описание	Описание
401	Unauthorized	JWT токен неверен или истёкло его время действия.
200	OK	Аудиозапись успешно создана.
400	Bad request	Один или несколько параметров не задано.
406	Not acceptable	Файл неверен (Не является `audio/mp3`).

Получение информации об аудиозаписи

GET			/api/playlist/{playlistId}/song/{id}

{id} необходимо заменить на уникальный идентификатор требуемого аудиозаписи.

Ответ: JSON описание аудиозаписи.

Коды ответа:

Код	HTTP описание	Описание
401	Unauthorized	JWT токен неверен или истёкло его время действия.
200	OK	Запрос успешно выполнен.
404	Not Found	Плэйлист или аудиозапись не найдены, либо аудиозапись находится в `internal` плэйлисте другого пользователя.

Воспроизведение MP3

Для того, чтобы воспроизвести аудиозапись (начать процесс скачивания) необходимо отправить запрос на следующий endpoint:

GET			/api/playlist/{playlistId}/song/{id}/mp3

{id} необходимо заменить на уникальный идентификатор требуемого аудиозаписи.

Ответ: MP3 файл.

Коды ответа:

Код	HTTP описание	Описание
401	Unauthorized	JWT токен неверен или истёкло его время действия.
200	OK	Инициализация скачивания MP3.
404	Not Found	Плэйлист или аудиозапись не найдены, либо аудиозапись находится в `internal` плэйлисте другого пользователя.

Получить аудиозаписи из плэйлиста

Чтобы получить список аудио из интересующего плэйлиста, необходимо послать запрос:

GET			/api/playlist/{playlistId}/songs

Ответ: JSON-массив аудиозаписей пользователя из выбранного плэйлиста. JSON представление ответа:

{
    "content": [
        {
            "id": "c1ac227d-7075-48fc-b5f9-c99667ff884e",
			"playlistId": "c1ac227d-7075-48fc-b5f9-c99667ff884e",
            "title": "Весёлая песня",
            "artist": "Весёлый артист",
            "uploadDate": "2019-10-17T15:50:34.475+0000"
        },
        {
	        ...
        }
    ]
}

В массиве content находятся JSON описание аудио.

Код	HTTP описание	Описание
401	Unauthorized	JWT токен неверен или истёкло его время действия.
200	OK	Запрос выполнен успешно.
404	Not Found	Плэйлист или аудиозапись не найдены, либо аудиозапись находится в `internal` плэйлисте другого пользователя.

Получить собственные аудиозаписи

Есть возможность получить все свои аудиозаписи из разных плэйлистов. Чтобы сделать это - необходимо послать GET запрос:

GET			/api/songs

Ответ: JSON-массив аудиозаписей пользователя из всех плэйлистов. JSON представление ответа:

{
    "content": [
        {
            "id": "c1ac227d-7075-48fc-b5f9-c99667ff884e",
			"playlistId": "c1ac227d-7075-48fc-b5f9-c99667ff884e",
            "title": "Весёлая песня",
            "artist": "Весёлый артист",
            "uploadDate": "2019-10-17T15:50:34.475+0000"
        },
        {
	        ...
        }
    ]
}

В массиве content находятся JSON описание аудио.

Код	HTTP описание	Описание
401	Unauthorized	JWT токен неверен или истёкло его время действия.
200	OK	Запрос выполнен успешно.
404	Not Found	Альбом или аудиозапись не найдены, либо аудиозапись находится в `internal` плэйлисте другого пользователя.

Обновление аудиозаписи

Обновление аудиозаписи очень похоже на создание аудиозаписи. Отличие лишь в том, что обновить уже существующий аудиофайл не выйдет, только метаданные. Для обновления аудиозаписи нужно отправить запрос:

PUT 		/api/playlist/{playlistId}/song/{id}

Со следующим JSON содержимым:

{
    "title": "<НОВЫЙ ЗАГОЛОВОК АУДИОЗАПИСИ>",
    "artist": "<НОВОЕ ИМЯ АРТИСТА АУДИОЗАПИСИ>"
}

В случае успешного редактирования аудиозаписи - вы получите JSON ответ, содержащий полное описание аудиозаписи.

Коды ответа:

Код	HTTP описание	Описание
401	Unauthorized	JWT токен неверен или истёкло его время действия.
200	OK	Запрос выполнен успешно.
400	Bad request	Один или несколько параметров не задано.
404	Not Found	Плэйлист или аудиозапись не найдены, либо аудиозапись находится у другого пользователя.

Удаление аудиозаписи

Для удаления аудиозаписи необходимо отправить запрос:

DELETE			/api/playlist/{playlistId}/song/{id}

Ответ не содержит тела.

Коды ответа:

Код	HTTP описание	Описание
401	Unauthorized	JWT токен неверен или истёкло его время действия.
200	OK	Аудиозапись удалена успешно.
404	Not Found	Плэйлист или аудиозапись не найдены, либо аудиозапись находится у другого пользователя.

Вместо заключения

Прошу принять к сведению то, что данное API является не конечным и возможны некоторые ошибки и доработки. Пожалуйста, не сердитесь :) В любом случае: Пишите мне все свои вопросы и предложения :)

(с) Тумасов Руслан Дмитриевич. 18/10/2019 00:50 (GMT +7)

Edited on: 20/10/2019 19:12

Edited on: 23/10/2019 23:31

Edited on: 28/11/2019 21:57

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
css		css
fonts		fonts
images		images
js		js
README.md		README.md
index.html		index.html
login.html		login.html
test.html		test.html

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Music Server backend API

MServer

API

Регистрация пользователя

Авторизация пользователя

Плэйлисты

Создание плэйлиста

Получение информации об плэйлисте

Получить свои плэйлисты

Получить плэйлисты пользователя

Обновление плэйлиста

Удаление плэйлиста

Аудиозаписи

Загрузка аудиозаписи в плэйлист

Получение информации об аудиозаписи

Воспроизведение MP3

Получить аудиозаписи из плэйлиста

Получить собственные аудиозаписи

Обновление аудиозаписи

Удаление аудиозаписи

Вместо заключения

About

Releases

Packages

Languages

Rusnura/music-portal-frontend

Folders and files

Latest commit

History

Repository files navigation

Music Server backend API

MServer

API

Регистрация пользователя

Авторизация пользователя

Плэйлисты

Создание плэйлиста

Получение информации об плэйлисте

Получить свои плэйлисты

Получить плэйлисты пользователя

Обновление плэйлиста

Удаление плэйлиста

Аудиозаписи

Загрузка аудиозаписи в плэйлист

Получение информации об аудиозаписи

Воспроизведение MP3

Получить аудиозаписи из плэйлиста

Получить собственные аудиозаписи

Обновление аудиозаписи

Удаление аудиозаписи

Вместо заключения

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages