API: /stories

Korrekted

Last updated January 20, 2020 1:42am

Общее

Этот раздел API посвящён запросу данных об историях, т.е. экранах, на которых пользователь включает аудиозапись рассказа

вызов /stories/list — позволяет получить перечень актуальных историй
вызов /stories/all — позволяет получить перечень и наполнение актуальных историй
вызов /stories/get — получает конкретную конфигурацию истории
вызов /stories/check — быстрая проверка доступности контента для пользователя (проверка наличия доступа или подписки к платному контенту)

/list

Описание: предоставляет информацию про все доступные истории
Полный путь к методу: https://www.s1eep.app/api/stories/list

Тип запроса: POST

Требования безопасности: API-ключ

Дополнительные ожидаемые параметры:

hash — сохранённый клиентом хеш с прошлого раза, в случае совпадения с актуальным (поле stories_hash) будет пустой ответ, необязательно

Дополнительные возвращаемые параметры (в случае отсутствия или несовпадения переданного hash'а):

stories — массив данных об историях, каждый элемент является словарём со следующими полями
- id — идентификатор истории, который нужно использовать при запросе о данных конкретной истории
- name — имя истории для отображения в списке
- paid — флаг true/false, индикатор платного контента
- sort — порядковый номер контента в списке
- reader — имя озвучивающего историю
- length_secs — длина истории в секундах
- image_story_url — полный URL для картинки, которая представляет историю
- image_reader_url — полный URL для фотографии озвучивающего историю
- story_hash — хэш конкретной истории, чтобы при совпадении с ранее полученным ответом (если он был) не пересохранять контент
deleted_stories — массив с идентификаторами удалённых историй для синхронизации кеша
stories_hash — хэш массива stories, чтобы при совпадении с ранее полученным ответом (если он был) не перерисовывать экран

Пример ответа в случае несовпадения кэша:

{
    "_code": 200,
    "_msg": "OK",
    "_need_payment": false,
    "_data": {
        "stories": [
            {
                "id": 15,
                "name": "Fallen  Leaves",
                "paid": false,
                "sort": 0,
                "reader": "Henry David Thoreau",
                "length_secs": 720,
                "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760178Card_02@jpg.jpg",
                "image_reader_url": null,
                "story_hash": "c4e7ea30226f2a973b93879eb3a05f32"
            },
            {
                "id": 11,
                "name": "The Bird of Popular Song",
                "paid": true,
                "sort": 1,
                "reader": "Hans Christian Andersen",
                "length_secs": 480,
                "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760168Card_01@jpg.jpg",
                "image_reader_url": null,
                "story_hash": "32b61e16597746c6a98137afb1cc86d1"
            },
            {
                "id": 16,
                "name": "A Dream of Songs Unsung",
                "paid": true,
                "sort": 2,
                "reader": "Julia Caroline Dorr",
                "length_secs": 660,
                "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760189Card_03@jpg.jpg",
                "image_reader_url": null,
                "story_hash": "db935a64c808e282c566a33132c9bbd6"
            },
            {
                "id": 17,
                "name": "Little Brother",
                "paid": true,
                "sort": 3,
                "reader": "Madeline Z. Doty",
                "length_secs": 900,
                "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760197Card_04@jpg.jpg",
                "image_reader_url": null,
                "story_hash": "376384e2a0b972a5f7d66034a8409312"
            },
            {
                "id": 19,
                "name": "Candilli",
                "paid": true,
                "sort": 5,
                "reader": "James Elroy Flecker",
                "length_secs": 300,
                "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760217Card_06@jpg.jpg",
                "image_reader_url": null,
                "story_hash": "8111e4978ab773ab80b140327f013a37"
            },
            {
                "id": 20,
                "name": "Flowers",
                "paid": true,
                "sort": 6,
                "reader": "James Russell Lowell",
                "length_secs": 420,
                "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760223Card_07@jpg.jpg",
                "image_reader_url": null,
                "story_hash": "d5074edfa7b2b89f21fb72d3e511fba5"
            },
            {
                "id": 21,
                "name": "The Perdu",
                "paid": true,
                "sort": 7,
                "reader": "Sir Charles G. D. Roberts",
                "length_secs": 1920,
                "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760231Card_08@jpg.jpg",
                "image_reader_url": null,
                "story_hash": "61bbcf57619b62367f3b7f0a47790aa6"
            },
            {
                "id": 22,
                "name": "The Forest",
                "paid": true,
                "sort": 8,
                "reader": "Georgette Leblanc",
                "length_secs": 1620,
                "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760240Card_09@jpg.jpg",
                "image_reader_url": null,
                "story_hash": "a3d57007173193a894e751ce19fe2dc0"
            },
            {
                "id": 23,
                "name": "The Tinder-Box",
                "paid": true,
                "sort": 9,
                "reader": "Hans Christian Andersen",
                "length_secs": 960,
                "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760249Card_10@jpg.jpg",
                "image_reader_url": null,
                "story_hash": "f5fde157b09c312e1e760ee68b802c37"
            }
        ],
        "deleted_stories": [
            18,
            24
        ],
        "stories_hash": "e32d25219cd914406b6c2a3715738bc6"
    }
}

Пример ответа в случае совпадения хеша:

{
    "_code": 200,
    "_msg": "OK",
    "_need_payment": false,
    "_data": "{}"
}

/all

Описание: предоставляет полную информацию про все доступные истории (фактически является сочетанием /list + /get)
Полный путь к методу: https://www.s1eep.app/api/stories/all

Тип запроса: POST

Требования безопасности: API-ключ

Дополнительные ожидаемые параметры:

hash — сохранённый клиентом хеш с прошлого раза, в случае совпадения с актуальным (поле stories_hash) будет пустой ответ, необязательно

Дополнительные возвращаемые параметры (в случае отсутствия или несовпадения переданного hash'а):

stories — массив данных об историях, каждый элемент является словарём со следующими полями
- id — идентификатор истории, который нужно использовать при запросе о данных конкретной истории
- name — имя истории для отображения в списке
- paid — флаг true/false, индикатор платного контента
- sort — порядковый номер контента в списке
- reader — имя озвучивающего историю
- length_secs — длина истории в секундах
- image_story_url — полный URL для картинки, которая представляет историю
- image_reader_url — полный URL для фотографии озвучивающего историю
- story_hash — хэш конкретной истории, чтобы при совпадении с ранее полученным ответом (если он был) не пересохранять контент
- ambient_sound — словарь о звуке окружающей среды, состоящий из следующих ключей:
  - id — идентификатор звука
  - sound_url — полный URL к файлу со звуком
  - sound_secs — длина звука в секундах
- reading_sound — словарь о дорожке с чтением, состоящий из следующих ключей:
  - id — идентификатор звука
  - sound_url — полный URL к файлу со звуком
  - sound_secs — длина звука в секундах
deleted_stories — массив с идентификаторами удалённых историй для синхронизации кеша
stories_hash — хэш массива stories, чтобы при совпадении с ранее полученным ответом (если он был) не перерисовывать экран

Пример ответа в случае несовпадения кэша:

{
    "_code": 200,
    "_msg": "OK",
    "_need_payment": false,
    "_data": {
        "stories": [
            {
                "id": 15,
                "name": "Fallen  Leaves",
                "paid": false,
                "sort": 0,
                "reader": "Henry David Thoreau",
                "length_secs": 720,
                "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760178Card_02@jpg.jpg",
                "image_reader_url": null,
                "story_hash": "c4e7ea30226f2a973b93879eb3a05f32",
                "ambient_sound": null,
                "reading_sound": {
                    "id": 84,
                    "sound_url": "https://www.s1eep.app/readings/2019/11/1574501730Henry David Thoreau - Fallen Leaves - Peter Yearsley - Nonfiction, Philosophy.mp3",
                    "sound_secs": 729
                }
            },
            {
                "id": 11,
                "name": "The Bird of Popular Song",
                "paid": true,
                "sort": 1,
                "reader": "Hans Christian Andersen",
                "length_secs": 480,
                "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760168Card_01@jpg.jpg",
                "image_reader_url": null,
                "story_hash": "32b61e16597746c6a98137afb1cc86d1",
                "ambient_sound": null,
                "reading_sound": {
                    "id": 79,
                    "sound_url": "https://www.s1eep.app/readings/2019/11/1574410033Hans Christian Andersen - The Bird of Popular Song - Trisha Rose (thestorygirl) - Myths, Legends & Fairy Tales.mp3",
                    "sound_secs": 501
                }
            },
            {
                "id": 16,
                "name": "A Dream of Songs Unsung",
                "paid": true,
                "sort": 2,
                "reader": "Julia Caroline Dorr",
                "length_secs": 660,
                "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760189Card_03@jpg.jpg",
                "image_reader_url": null,
                "story_hash": "db935a64c808e282c566a33132c9bbd6",
                "ambient_sound": null,
                "reading_sound": {
                    "id": 85,
                    "sound_url": "https://www.s1eep.app/readings/2019/11/1574501752Julia Caroline Dorr - A Dream of Songs Unsung - Sarah Sellari - Poetry.mp3",
                    "sound_secs": 635
                }
            },
            {
                "id": 17,
                "name": "Little Brother",
                "paid": true,
                "sort": 3,
                "reader": "Madeline Z. Doty",
                "length_secs": 900,
                "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760197Card_04@jpg.jpg",
                "image_reader_url": null,
                "story_hash": "376384e2a0b972a5f7d66034a8409312",
                "ambient_sound": null,
                "reading_sound": {
                    "id": 86,
                    "sound_url": "https://www.s1eep.app/readings/2019/11/1574501990Madeline Z. Doty - Little Brother - Arie - Fiction, Anthologies.mp3",
                    "sound_secs": 918
                }
            },
            {
                "id": 19,
                "name": "Candilli",
                "paid": true,
                "sort": 5,
                "reader": "James Elroy Flecker",
                "length_secs": 300,
                "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760217Card_06@jpg.jpg",
                "image_reader_url": null,
                "story_hash": "8111e4978ab773ab80b140327f013a37",
                "ambient_sound": null,
                "reading_sound": {
                    "id": 88,
                    "sound_url": "https://www.s1eep.app/readings/2019/11/1574502048James Elroy Flecker - Candilli -  Ben Lindsey-Clark - Essays & Short Works, Literary Criticism.mp3",
                    "sound_secs": 325
                }
            },
            {
                "id": 20,
                "name": "Flowers",
                "paid": true,
                "sort": 6,
                "reader": "James Russell Lowell",
                "length_secs": 420,
                "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760223Card_07@jpg.jpg",
                "image_reader_url": null,
                "story_hash": "d5074edfa7b2b89f21fb72d3e511fba5",
                "ambient_sound": null,
                "reading_sound": {
                    "id": 89,
                    "sound_url": "https://www.s1eep.app/readings/2019/11/1574502072James Russell Lowell - Flowers - Sarah Sellari - Poetry.mp3",
                    "sound_secs": 390
                }
            },
            {
                "id": 21,
                "name": "The Perdu",
                "paid": true,
                "sort": 7,
                "reader": "Sir Charles G. D. Roberts",
                "length_secs": 1920,
                "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760231Card_08@jpg.jpg",
                "image_reader_url": null,
                "story_hash": "61bbcf57619b62367f3b7f0a47790aa6",
                "ambient_sound": null,
                "reading_sound": {
                    "id": 90,
                    "sound_url": "https://www.s1eep.app/readings/2019/11/1574502298Sir Charles G. D. Roberts - The Perdu.mp3",
                    "sound_secs": 1928
                }
            },
            {
                "id": 22,
                "name": "The Forest",
                "paid": true,
                "sort": 8,
                "reader": "Georgette Leblanc",
                "length_secs": 1620,
                "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760240Card_09@jpg.jpg",
                "image_reader_url": null,
                "story_hash": "a3d57007173193a894e751ce19fe2dc0",
                "ambient_sound": null,
                "reading_sound": {
                    "id": 91,
                    "sound_url": "https://www.s1eep.app/readings/2019/11/1574502334Georgette Leblanc - The Forest - MaryAnn - Children's Fiction.mp3",
                    "sound_secs": 1603
                }
            },
            {
                "id": 23,
                "name": "The Tinder-Box",
                "paid": true,
                "sort": 9,
                "reader": "Hans Christian Andersen",
                "length_secs": 960,
                "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760249Card_10@jpg.jpg",
                "image_reader_url": null,
                "story_hash": "f5fde157b09c312e1e760ee68b802c37",
                "ambient_sound": null,
                "reading_sound": {
                    "id": 92,
                    "sound_url": "https://www.s1eep.app/readings/2019/11/1574502506Hans Christian Andersen - The Tinder-Box - doonaboon -  Children's Fiction, Myths, Legends & Fairy Tales, General Fiction.mp3",
                    "sound_secs": 980
                }
            }
        ],
        "deleted_stories": [
            18,
            24
        ],
        "stories_hash": "e32d25219cd914406b6c2a3715738bc6"
    }
}

Пример ответа в случае совпадения хеша:

{
    "_code": 200,
    "_msg": "OK",
    "_need_payment": false,
    "_data": "{}"
}

/get

Описание: предоставляет информацию о конкретной истории

Полный путь к методу: https://www.s1eep.app/api/stories/get

Тип запроса: POST

Требования безопасности: API-ключ + пользовательский токен (опционально)

Дополнительные ожидаемые параметры:

_user_token — пользовательский токен при наличии, чтобы получить доступ к платному контенту, необязательно
story_id — идентификатор истории
hash — сохранённый клиентом хеш с прошлого раза, в случае совпадения с актуальным (поле stories_hash) будет пустой ответ, необязательно

Дополнительные возвращаемые параметры (в случае отсутствия или несовпадения переданного hash'а):

story — словарь данных о запрошенной истории
- id — идентификатор истории (совпадает с запрошенным story_id)
- name — имя истории
- paid — флаг true/false, индикатор платного контента
- sort — порядковый номер контента в списке
- reader — имя озвучивающего историю
- image_story_url — полный URL для картинки, которая представляет историю
- image_reader_url — полный URL для фотографии озвучивающего историю
- ambient_sound — словарь о звуке окружающей среды, состоящий из следующих ключей:
  - id — идентификатор звука
  - sound_url — полный URL к файлу со звуком
  - sound_secs — длина звука в секундах
- reading_sound — словарь о дорожке с чтением, состоящий из следующих ключей:
  - id — идентификатор звука
  - sound_url — полный URL к файлу со звуком
  - sound_secs — длина звука в секундах
story_hash — хэш данных об истории, чтобы при совпадении с ранее полученным ответом (если он был) не перезагружать данные

Пример ответа в случае несовпадения кэша:

{
    "_code": 200,
    "_msg": "OK",
    "_need_payment": false,
    "_data": {
        "story": {
            "id": 15,
            "name": "Fallen  Leaves",
            "paid": false,
            "sort": 0,
            "reader": "Henry David Thoreau",
            "image_story_url": "https://www.s1eep.app/stories/2019/11/1574760178Card_02@jpg.jpg",
            "image_reader_url": null,
            "ambient_sound": null,
            "reading_sound": {
                "id": 84,
                "sound_url": "https://www.s1eep.app/readings/2019/11/1574501730Henry David Thoreau - Fallen Leaves - Peter Yearsley - Nonfiction, Philosophy.mp3",
                "sound_secs": 729
            }
        },
        "story_hash": "c4e7ea30226f2a973b93879eb3a05f32"
    }
}

Пример ответа в случае совпадения хеша:

{
    "_code": 200,
    "_msg": "OK",
    "_need_payment": false,
    "_data": "{}"
}

/check

Описание: быстрая проверка доступности контента для пользователя (проверка наличия доступа или подписки к платному контенту)

Полный путь к методу: https://www.s1eep.app/api/stories/check

Тип запроса: POST

Требования безопасности: API-ключ + пользовательский токен (опционально)

Дополнительные ожидаемые параметры:

_user_token — пользовательский токен при наличии, чтобы проверить доступ к платному контенту для конкретного пользователя приложения, необязательно
story_id — идентификатор истории

Дополнительные возвращаемые параметры:

нет

Пример ответа в случае возможности доступа:

{
    "_code": 200,
    "_msg": "OK",
    "_need_payment": false,
    "_data": "{}"
}

Пример ответа в случае невозможности доступа:

{
    "_code": 403,
    "_msg": "Active subscription required",
    "_need_payment": true,
    "_data": "{}"
}