api.raml

#%RAML 1.0
title: ProstoTV
version: 1
baseUri: https://api.prosto.tv/v1
mediaType: application/json
types: !include ./types.raml

securitySchemes:
  bearer:
    type: x-bearer
    describedBy:
      headers:
        Authorization:
          description: Заголовок для авторизації за токеном
          example: Bearer 00112233445566778899aabbccddeeff

/objects:
  securedBy: bearer
  post:
    description: Додавання користувача
    body:
      type: object
      properties:
        first_name?: string
        middle_name?: string
        last_name?: string
        note?: string
        phone?: string
        password?: string
    responses:
      201:
        description: Користувача додано
        body:
          type: object
          example: |
            {
              "id": 123456,
              "password": 12345678,
              "status": "active",
              "balance": 0,
              "bonus": 0,
              "ebs_url": 'https://{ebs_url}/{object_id}/more/services',
              "bundles": [],
              "services": [],
              "devices": [],
              "playlists": []
            }
  /{account_id}:
    securedBy: bearer
    uriParameters:
      account_id:
        type: integer
        description: Account ID
    get:
      description: Отримання даних користувача
      responses:
        200:
          body:
            type: object
            properties:
              id: integer
              status: ['none', 'active', 'blocked', 'disconnected', 'deleted']
              balance: number
              bonus: number
              contacts: array
              date_create: string
              bundles: array
              services: array
              devices: array
              playlists: array
            example: |
              {
                "id": 123456,
                "status": "active",
                "balance": 0,
                "bonus": 0,
                "ebs_url": 'https://{ebs_url}/{object_id}/more/services',
                "contacts": [ "012 3456789", "098 7654321"...]
                "date_create": "2015-02-08"
                "bundles": [
                  {
                    "id": 40,
                    "main": 1,
                    "bundles": [],
                    "name_ru": "Украина",
                    "name_uk": "Україна",
                    "channels_count": 38,
                    "cost": 39
                  },
                  {
                    "id": 50,
                    "main": 1,
                    "bundles": [40],
                    "name_ru": "Вселенная",
                    "name_uk": "Всесвіт"
                    "channels_count": 144,
                    "cost": 79
                  }
                ],
                "services": [
                  {
                    "id": 50,
                    "created": "2018-11-01 01:00:14",
                    "name_ru": "IPTV Вселенная",
                    "name_uk": "IPTV Всесвіт",
                    "active": 1,
                    "auto_renewal": 1,
                    "cost": 79,
                    "main": 1,
                    "channels_count": 144,
                    "bundles": [40],
                    "stop": "2019-01-01"
                  }
                ],
                "devices": [
                  {
                    "id": "123456_3",
                    "created": "2018-11-01 02:01:04",
                    "updated": "2018-12-08 19:54:17",
                    "password": "520630",
                    "device": "M01PR100",
                    "comment": "Телевізор на кухні"
                  }
                ],
                "playlists": [
                  {
                    "id": "secret",
                    "created": "2018-12-01 12:14:34",
                    "updated": "2018-12-08 19:54:17",
                    "genres": 1,
                    "comment": "Домашній ПК",
                    "ip": "90.100.110.120",
                    "url": "http://my.prosto.tv/secret.m3u"
                  }
                ]
              }
    delete:
      description: Видалення акаунту
      responses:
        200:
          description: Акаунт видалено
          body:
            type: object
            example: |
              {
                "id": "123456",
                "status": "deleted"
              }
        305:
          description: Акаунт видалено не повністю
          body:
            type: Error
        404:
          description: Акаунт вже видалено
          body:
            type: Error
    /devices:
      description: Робота з пристроями
      securedBy: bearer
      get:
        description: Отримання списку всіх пристроїв
        responses:
          200:
            body:
              properties:
                devices:
                  type: array
                  items: Device
                  example: !include types/device.json
      post:
        description: Додавання пристрою
        responses:
          201:
            description: Пристрій додано
            body:
              type: Device
              example: !include types/device.json
          406:
            description: Досягнуто ліміт пристроїв
            body:
              type: Error
      /{device_id}:
        securedBy: bearer
        uriParameters:
          device_id:
            type: string
            description: Ідентифікатор (логін) пристрою
            example: "000000_0"
        delete:
          description: Видалення пристрою
          responses:
            200:
              description: Пристрій видалено
            400:
              description: Некоректний запит
              body:
                type: Error
            404:
              description: Пристрій не знайдено
              body:
                type: Error
        put:
          description: Додавання коментаря до пристрою
          body:
            properties:
              comment?: string
          responses:
            201:
              description: Коментар додано
              body:
                type: Device
                example: !include types/device.json
            400:
              description: Невірний id пристрою
              body:
                type: Error
            204:
              description: Коментар не задано
              body:
                type: Error
    /playlists:
      description: Керування плейлистами
      securedBy: bearer
      get:
        description: Отримання списку всіх плейлистів
        responses:
          200:
            body:
              properties:
                playlists:
                  type: array
                  items: Playlist
                  example: !include types/playlist.json
      post:
        description: Додавання плейлиста
        responses:
          201:
            description: Плейлист додано
            body:
              type: Playlist
              example: !include types/playlist.json
          406:
            description: Досягнуто ліміт
            body:
              type: Error
      /{playlist_id}:
        securedBy: bearer
        uriParameters:
          playlist_id:
            type: string
            description: Ідентифікатор (secret) плейлиста
            example: "xxxxxxxx"
        delete:
          description: Видалення плейлиста
          responses:
            200:
              description: Плейлист видалено
            400:
              description: Некоректний запит
              body:
                type: Error
            404:
              description: Плейлист не знайдено
              body:
                type: Error
        put:
          description: Додавання коментаря, увімкнення/вимкнення групування за жанрами
          body:
            properties:
              comment?: string
              genres?: 0|1
              tv_guide?: 0|1
              available_mode?:
                description: Залишити в плейлисті лише доступні канали
                type: 0|1
          responses:
            201:
              description: Плейлист змінено
              body:
                type: Playlist
                example: !include types/playlist.json
            400:
              description: Параметри не вказано
              body:
                type: Error
            500:
              description: Внутрішня помилка
              body:
                type: Error
    /workoncredit:
      securedBy: bearer
      post:
        description: Активація роботи в кредит
        responses:
          200:
            description: Роботу в кредит активовано
          400:
            description: Не вдалося активувати послугу
            body:
              type: Error
          402:
            description: Активація послуги недоступна
            body:
              type: Error
    /operations:
      securedBy: bearer
      post:
        description: Проведення операції
        body:
          type: object
          properties:
            operation_id: integer
            sum: number
          example: |
            {
              "operation_id": 20,
              "sum": 120.0
            }
        responses:
          201:
            description: Операцію проведено
            body:
              type: Operation
              example: |
                {
                  "id": 123456,
                  "transaction_id": 123456,
                  "object_id": 123456,
                  "created": "2018-12-01 10:10:43",
                  "sum": 79.00,
                  "balance": 79.00
                }
          400:
            description: Некоректний запит
            body:
              type: Error
          403:
            description: Вказаний тип операції не дозволений
            body:
              type: Error
          404:
            description: Вказаний тип операції не знайдено
            body:
              type: Error
          500:
            description: Внутрішня помилка
            body:
              type: Error
    /status:
      securedBy: bearer
      post:
        description: Відключення/увімкнення облікового запису
        body:
          type: object
          properties:
            status: string
        responses:
          201:
            description: Статус облікового запису змінено
            body:
              type: Status
              example: |
                {
                  "id": 123456,
                  "status": "disconnected"
                }
          400:
            description: Некоректний запит
            body:
              type: Error
          203:
            description: Невірний статус
            body:
              type: Error
          304:
            description: Статус вже встановлено
            body:
              type: Error
          402:
            description: Недостатньо коштів
            body:
              type: Error
          500:
            description: Внутрішня помилка
            body:
              type: Error
    /services:
      securedBy: bearer
      post:
        description: Активація послуги
        body:
          type: object
          properties:
            id: integer
            auto_renewal: integer
        responses:
          201:
            description: Послугу активовано
            body:
              type: Service
              example: |
                {
                  "id": 50,
                  "created": "2018-11-01 01:00:14",
                  "name_ru": "IPTV Вселенная",
                  "name_uk": "IPTV Всесвіт",
                  "active": 1,
                  "auto_renewal": 1,
                  "cost": 79,
                  "main": 1,
                  "channels_count": 230,
                  "bundles": [40],
                }
          400:
            description: Некоректний запит
            body:
              type: Error
          402:
            description: Недостатньо коштів
            body:
              type: Error
          403:
            description: Немає прав для активації вказаної послуги
            body:
              type: Error
          404:
            description: Послугу не знайдено
            body:
              type: Error
          500:
            description: Внутрішня помилка
            body:
              type: Error
      /{service_id}:
        securedBy: bearer
        delete:
          description: Відключення послуги
          body:
            type: object
          responses:
            201:
              description: Послугу активовано
              body:
                type: Service
                example: |
                  {
                    "id": 50,
                    "name_ru": "IPTV Вселенная",
                    "name_uk": "IPTV Всесвіт",
                    "active": 1,
                    "auto_renewal": 0,
                    "cost": 79,
                    "main": 1,
                    "channels_count": 230,
                    "bundles": [40],
                    "stop": "2019-01-01"
                  }
            400:
              description: Некоректний запит
              body:
                type: Error
            403:
              description: Немає прав для роботи з вказаною послугою
              body:
                type: Error
            404:
              description: Послугу не знайдено
              body:
                type: Error
            500:
              description: Внутрішня помилка
              body:
                type: Error
    /contacts:
      securedBy: bearer
      post:
        description: Додавання номера телефону
        body:
          type: object
          properties:
            phone: string
        responses:
          201:
            description: Номер додано
            body:
              type: object
              example: |
                {
                  "id": 123456,
                  "contact": "012 3456789",
                  "status": "added"
                }
          400:
            description: Некоректний запит
            body:
              type: Error
          6:
            description: Duplicate entry data
            body:
              type: Error
      /{phone}:
        securedBy: bearer
        delete:
          description: Видалення номера телефону
          responses:
            200:
              description: Номер видалено
              body:
                type: object
                example: |
                  {
                    "id": 123456,
                    "contact": "012 3456789",
                    "status": "deleted"
                  }
            400:
              description: Некоректний запит
              body:
                type: Error
            406:
              description: No phone number found
              body:
                type: Error
    /password:
      securedBy: bearer
      put:
        description: Зміна пароля. Мінімальна довжина пароля — 8 символів
        body:
          properties:
            password?: string
        responses:
          200:
            description: Пароль змінено
            body:
              type: object
              example:
                {
                  "id": 123456,
                  "newPassword": "12345678"
                }
          400:
            description: Некоректний пароль
            body:
              type: Error
          500:
            description: Внутрішня помилка
            body:
              type: Error
    /token:
      securedBy: bearer
      post:
        description: Створення тимчасового токена для авторизації пристрою
        responses:
          200:
            description: Токен створено, час життя токена — 2 хвилини
            body:
              type: object
              example:
                {
                  "account_id": 123456,
                  "date_create": "2020-03-25 15:42:37",
                  "date_expire": "2020-03-25 15:44:37",
                  "token": "01234"
                }
          500:
            description: Внутрішня помилка
            body:
              type: Error
/search:
  /accounts:
    securedBy: bearer
    get:
      description: Отримати список усіх акаунтів
      responses:
        200:
          body:
            type: object
            properties:
              count: integer
              accounts: integer[]
        500:
          description: Внутрішня помилка
          body:
            type: Error
    post:
      description: Отримати список акаунтів згідно із заданими умовами
      body:
        type: object
        properties:
          parameter: string status|phone|service_id|first_name|last_name|middle_name  # параметр пошуку
          value: string
      responses:
        200:
          body:
            type: object
            properties:
              count: integer
              property: string
              value: string
              accounts: integer[]
        500:
          description: Внутрішня помилка
          body:
            type: Error
  /bundles:
    securedBy: bearer
    get:
      description: Отримання списку доступних пакетів
      responses:
        200:
          description: Список пакетів для користувачів, які вже створені або будуть створені через API
          body:
            type: array
            items: Bundles
            example: !include types/bundle.json
        500:
          description: Помилка сервера — потрібно перевірити налаштування акаунту оператора
          body:
            type: Error
/tokens:
  post:
    description: Отримання токена
    body:
      type: object
      properties:
        login: string
        password: string
    responses:
      201:
        description: Токен створено
        body:
          type: Token
          example: |
            {
              "token": "00112233445566778899aabbccddeeff"
            }
      400:
        description: Некоректний запит, додаткову інформацію дивіться у відповіді
        body:
          type: Error
      404:
        description: Вказану пару логін/пароль не знайдено
        body:
          type: Error