API: /sound_sets

Korrekted
Korrekted
Last updated 

Общее

Этот раздел API посвящён отображению и сохранению наборов звуков для пользователей:
  • вызов /sound_sets/create для создания набора звуков
  • вызов /sound_sets/update для обновления существующего набора звуков
  • вызов /sound_sets/list для того, чтобы отобразить сохранённые наборы звуков пользователя
  • вызов /sound_sets/show для отображения состава «анонимных» наборов звуков

Создание набора звуков является платной фичей. Во втором случае созданный набор будет «анонимным» и информацию о его составе Таким образом данный API работает только при наличии платного доступа у пользователя.

В случае наличия оплаченной подписки приложение должно при обращении к экрану Звуков считывать набор сцен (/list) и выстраивать список сохранённых наборов. При выборе сохранённого набора требуется вычитать его содержимое (звуки и их расположение на экране) через ендпоинт /show. Создание нового набора идёт через ендпоинт /create. В ответ ендпоинт будет возвращать идентификаторы созданного набора. При обновлении набора (перемещении значков звуков по экрану) требуется вызывать /update.


/create

Описание: сохраняет набор звуков для пользователя
Полный путь к методу: https://www.s1eep.app/api/sound_sets/create
Тип запроса: POST
Требования безопасности: API-ключ
Дополнительные ожидаемые параметры:
  • _user_token — для закрепления набора за конкретным пользователем (необязательно, в случае отсутствия набор будет «анонимным»)
  • name — название набора звуков
  • items[] — массив JSON-строчек с информацией о звуке с полями sound_id, x (координата 1) и y (координата 2). Пример: {"sound_id":10,"x":60.37,"y":33.56}
Дополнительные возвращаемые параметры:
  • sound_set_id — идентификатор созданного набора
Пример успешного ответа:
{
    "_code": 200,
    "_msg": "OK",
    "_need_payment": false,
    "_data": {
        "sound_set_id": 9
    }
}
Пример ошибки:
{
    "_code": 400,
    "_msg": "Data validation error:  The items field is required.",
    "_need_payment": false,
    "_data": "{}"
}


/list

Описание: отображает сохранённые наборы звуков пользователя
Полный путь к методу: https://www.s1eep.app/api/sound_sets/list
Тип запроса: POST
Требования безопасности: API-ключ + пользовательский токен
Дополнительные ожидаемые параметры:
  • нет
Дополнительные возвращаемые параметры:
  • sound_sets_id — массив словарей со следующими ключами:
    • id — идентификатор набора звуков
    • name — название набора звуков
    • sound_set_items_count — количество звуков в наборе
    • sound_set_items — массив словарей с информацией о звуках в наборе со следующими ключами:
      • sound_id — идентификатор звука
      • x — координата 1 звука
      • y — координата 2 звука
Пример ответа:
{
    "_code": 200,
    "_msg": "OK",
    "_need_payment": false,
    "_data": {
        "sound_sets": [
            {
                "id": 8,
                "name": "Another list",
                "sound_set_items_count": 3,
                "sound_set_items": [
                    {
                        "sound_id": 5,
                        "x": 60.37,
                        "y": 33.56
                    },
                    {
                        "sound_id": 2,
                        "x": 22.91,
                        "y": 11.16
                    },
                    {
                        "sound_id": 7,
                        "x": 88.91,
                        "y": 81.5
                    }
                ]
            }
        ]
    }
}


/show

Описание: показывает содержание «анонимных» наборов
Полный путь к методу: https://www.s1eep.app/api/sound_sets/show
Тип запроса: POST
Требования безопасности: API-ключ
Дополнительные ожидаемые параметры:
  • sound_set_ids[] — массив идентификаторов наборов
Дополнительные возвращаемые параметры:
  • sound_sets — массив словарей с данными о наборах. Включает в себя следующие поля:
    • id — идентификатор набора
    • name — название набора
    • sound_set_items — массив словарей с информацией о звуках в наборе со следующими ключами:
      • sound_id — идентификатор звука
      • x — координата 1 звука
      • y — координата 2 звука
Пример успешного ответа:
{
    "_code": 200,
    "_msg": "OK",
    "_need_payment": false,
    "_data": {
        "sound_sets": [
            {
                "id": 9,
                "name": "Anonymous list",
                "sounds": [],
                "sound_set_items": [
                    {
                        "sound_id": 10,
                        "x": 60.37,
                        "y": 33.56
                    },
                    {
                        "sound_id": 11,
                        "x": 22.91,
                        "y": 11.16
                    },
                    {
                        "sound_id": 9,
                        "x": 88.91,
                        "y": 81.5
                    }
                ]
            }
        ]
    }
}
Пример ошибки:
{
    "_code": 400,
    "_msg": "Data validation error:  The sound_set_ids field is required.",
    "_need_payment": false,
    "_data": "{}"
}