То или Это: документация API

Все запросы к API должны выполняться через HTTPS и быть представлены в таком виде:

https://api.thisorthat.ru/<method_name>

Для всех запросов, кроме /register, поддерживаются HTTP-методы GET и POST.
Выбор HTTP-метода ложится на плечи клиента, но стоит помнить, что запросы на изменение данных не должны кэшироваться. Параметры запроса могут быть переданны одним из трех способов:

• URL query string
• application/x-www-form-urlencoded
• multipart/form-data

Ответ содержит объект JSON, который всегда имеет логическое поле ok. Если ok равно true, значит, запрос был выполнен успешно и результат запроса можно найти в поле result. В случае неудачного запроса ok равно false, и суть ошибки объясняется в поле descriprion. Некоторые ошибки содержат необязательное поле parameters, которое поможет автоматически обработать ошибку. Все такие случаи подробно описаны в пояснениях к конкретным методам.
Для всех запросов сервер возвращает корректный код состояния HTTP-запроса.

• Все методы API не чувствительны к регистру
• Запросы должны выполняться с использованием кодировки UTF-8

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

/register

Метод служит для регистрации клиента и получения токена авторизации. Регистрацию следует выполнять только через POST.

Запрос

POST https://api.thisorthat.ru/register

Параметры запроса

Все параметры запроса являются обязательными

Пример запроса

curl --include --request POST --data 'client=vkontakte&uniqid=5655655' 'https://api.thisorthat.ru/register'

Ответ сервера

{
    "ok": true,
    "result": {
        "token": "1:0994f52572ab3f9432c77615c104db9c"
    }
}

В случае удачного выполнения запроса сервер возвращает параметр token, который представляет из себя user_id, отделенный двоеточием от 32-символьного хеша.

/getItems

Возвращает список из 30 вопросов, на которые пользователь ещё не ответил. Метод не возвращает отклоненные после модерации объекты.

Этот метод может изменять полe базы данных.

Запрос

GET|POST https://api.thisorthat.ru/getItems

Параметры запроса

Параметры, выделенные полужирным, являются обязательными.

Пример запроса

curl --include --request GET 'https://api.thisorthat.ru/getItems?token=1:0994f52572ab3f9432c77615c104db9c&status=approve'

Ответ сервера

{
    "ok": true,
    "result": {
        "items": [
            {
                "item_id": "1926",
                "first_text": "Остаться слепым на всю жизнь",
                "last_text": "Остаться глухим на всю жизнь",
                "status": "approved",
                "first_vote": 3443,
                "last_vote": 11679,
                "comments": null
            },
            {
                "item_id": "5043",
                "first_text": "Быть нервным",
                "last_text": "Быть ранимым",
                "status": "approved",
                "first_vote": 7630,
                "last_vote": 7751,
                "comments": "available"
            }
        ]
    }
}

Ответ сервера содержит список объектов items. Клиент может перемешать вопросы после получения.

Описание полей вопроса

/getMyItems

Метод возвращает вопросы, которые добавил текущий пользователь.

GET|POST https://api.thisorthat.ru/getMyItems

Параметры запроса

Параметры, выделенные полужирным, являются обязательными.

Пример запроса

curl --include --request GET 'https://api.thisorthat.ru/getMyItems?token=1:0994f52572ab3f9432c77615c104db9c&limit=2&offset=10'

Ответ сервера

{
    "ok": true,
    "result": {
        "items": [
            {
                "item_id": "11",
                "first_text": "Прожить в тюрьме год",
                "last_text": "Пролежать в коме 2 года",
                "reason": "abuse",
                "status": "rejected",
                "first_vote": 6414,
                "last_vote": 10598
            },
            {
                "item_id": "12",
                "first_text": "Хотеть чихнуть каждую секунду своей жизни но не иметь возможности сделать это",
                "last_text": "Икать до конца жизни",
                "status": "approved",
                "first_vote": 12194,
                "last_vote": 4712
            }
        ],
        "pages": {
            "count": 2,
            "offset": 10,
            "total": 247
        }
    }
}

Ответ сервера содержит список объектов items и список значений для пагинации pages.

Описание полей вопроса

Поле reason определено только для вопросов со статусом rejected.

Описание полей пагинации

Чтобы получить все 247 вопросов пользователя, нужно сделать три запроса по 100 вопросов со смещением 0, 100 и 200 соответственно.

/getCommentedItems

Метод возвращает вопросы, которые комментировал текущий пользователь в порядке комментирования от последнего к первому.

GET|POST https://api.thisorthat.ru/getCommentedItems

Параметры запроса

Параметры, выделенные полужирным, являются обязательными.

Пример запроса

curl --include --request GET 'https://api.thisorthat.ru/getCommentedItems?token=1:0994f52572ab3f9432c77615c104db9c&limit=2&offset=10'

Ответ сервера

{
    "ok": true,
    "result": {
        "items": [
            {
                "item_id": "11",
                "first_text": "Прожить в тюрьме год",
                "last_text": "Пролежать в коме 2 года",
                "status": "rejected",
                "comment_id": "42540",
                "first_vote": 6414,
                "last_vote": 10598
            },
            {
                "item_id": "12",
                "first_text": "Хотеть чихнуть каждую секунду своей жизни но не иметь возможности сделать это",
                "last_text": "Икать до конца жизни",
                "status": "approved",
                "comment_id": "42495",
                "first_vote": 12194,
                "last_vote": 4712
            }
        ],
        "pages": {
            "count": 2,
            "offset": 10,
            "total": 247
        }
    }
}

Ответ сервера содержит список объектов items и список значений для пагинации pages.

Описание полей вопроса

Поле status может содержать значение rejected, это значит, что вопрос был отклонен уже после его комментирования.

Описание полей пагинации

Чтобы получить все 247 вопросов пользователя, нужно сделать три запроса по 100 вопросов со смещением 0, 100 и 200 соответственно.

/addItem

Добавление нового вопроса от пользователя.

Запрос

GET|POST https://api.thisorthat.ru/addItem

Параметры запроса

Клиент должен провести предварительную фильтрацию вопросов.

Все параметры запроса являются обязательными.

Пример запроса

curl --include --request POST --data 'first_text=Visa&last_text=Mastercard' 'https://api.thisorthat.ru/addItem?token=1:0994f52572ab3f9432c77615c104db9c'

Ответ сервера

{
    "ok": true,
    "result": {
        "item_id": "10000"
    }
}

Ответ сервера содержит item_id типа String добавленного вопроса. В случае ошибки клиент может отобразить на своей стороне результат поля description.

Ответ сервера с ошибкой

{
    "ok": false,
    "description": "В нашей базе уже есть такой вопрос",
    "parameters": {
        "clone_id": "18007"
    }
}

В процессе добавления вопроса сервер проверяет текст на дубликаты. Если клон найден, сервер вернет ошибку и дополнительное поле parameters, содержащее параметр clone_id типа String с идентификатором похожего вопроса.

Если поле parameters.clone_id не пустое, клиент может предложить добавить вопрос в избранное.

/setViewed

Метод для добавления ответов пользователя. Позволяет отправить список значений одним запросом.

Запрос

GET|POST https://api.thisorthat.ru/setViewed

Параметры запроса

Если не удалось получить ответ на вопрос (например, пользователь отправил жалобу), но необходимо засчитать просмотр, то следует отправить значение skip.

Все параметры запроса являются обязательными.

Пример запроса

curl --include --request POST --data 'views[100]=first&views[245]=last&views[376]=skip' 'https://api.thisorthat.ru/setViewed?token=1:0994f52572ab3f9432c77615c104db9c'

Ответ сервера

{
    "ok": true,
    "result": true
}

В случае удачного выполнения сервер вернет true.

/getFavorite

Получение списка вопросов, добавленных текущим пользователем в избранное.

Запрос

GET|POST https://api.thisorthat.ru/getFavorite

Параметры запроса

Параметры, выделенные полужирным, являются обязательными.

Пример запроса

curl --include --request GET 'https://api.thisorthat.ru/getFavorite?token=1:0994f52572ab3f9432c77615c104db9c&limit=20&offset=10'

Ответ сервера

{
    "ok": true,
    "result": {
        "items": [
            {
                "item_id": "11",
                "first_text": "Прожить в тюрьме год",
                "last_text": "Пролежать в коме 2 года",
                "status": "rejected",
                "first_vote": 6414,
                "last_vote": 10598
            },
            {
                "item_id": "16",
                "first_text": "Хотеть чихнуть каждую секунду своей жизни но не иметь возможности сделать это",
                "last_text": "Икать до конца жизни",
                "status": "approved",
                "first_vote": 12194,
                "last_vote": 4712
            }
        ],
        "pages": {
            "count": 2,
            "offset": 0,
            "total": 2
        }
    }
}

Ответ сервера содержит список объектов items и список значений для пагинации pages.

Описание полей вопроса

Описание полей пагинации

/addFavorite

Добавление вопроса в список избранного.

Запрос

GET|POST https://api.thisorthat.ru/addFavorite

Параметры запроса

Все параметры запроса являются обязательными.

Пример запроса

curl --include --request POST --data 'item_id=10' 'https://api.thisorthat.ru/addFavorite?token=1:0994f52572ab3f9432c77615c104db9c'

Ответ сервера

{
    "ok": true,
    "result": true
}

В случае удачного выполнения, даже если вопрос уже был добавлен в избранное, сервер вернет true.

/deleteFavorite

Удаление вопроса из списка избранного.

Запрос

GET|POST https://api.thisorthat.ru/deleteFavorite

Параметры запроса

Все параметры запроса являются обязательными.

Пример запроса

curl --include --request POST --data 'item_id=10' 'https://api.thisorthat.ru/deleteFavorite?token=1:0994f52572ab3f9432c77615c104db9c'

Ответ сервера

{
    "ok": true,
    "result": true
}

В случае удачного выполнения, даже если вопроса не было в избранном, сервер вернет true.

/sendReport

Отправляет жалобу на конкретный вопрос.

Запрос

GET|POST https://api.thisorthat.ru/sendReport

Параметры запроса

Все параметры запроса являются обязательными.

Пример запроса

curl --include --request POST --data 'item_id=10&reason=typo' 'https://api.thisorthat.ru/sendReport?token=1:0994f52572ab3f9432c77615c104db9c'

Ответ сервера

{
    "ok": true,
    "result": true
}

В случае удачного выполнения сервер вернет true.

/cancelReport

Снимает жалобу с вопроса.

Запрос

GET|POST https://api.thisorthat.ru/cancelReport

Параметры запроса

Все параметры запроса являются обязательными.

Пример запроса

curl --include --request POST --data 'item_id=10' 'https://api.thisorthat.ru/cancelReport?token=1:0994f52572ab3f9432c77615c104db9c'

Ответ сервера

{
    "ok": true,
    "result": true
}

В случае удачного выполнения сервер вернет true.

/getComments

Получает список комментариев к вопросу.

Запрос

GET|POST https://api.thisorthat.ru/getComments

Параметры запроса

Параметры, выделенные полужирным, являются обязательными.

Пример запроса

curl --include --request GET 'https://api.thisorthat.ru/getComments?token=1:0994f52572ab3f9432c77615c104db9c&item_id=4&limit=2&offset=10'

Ответ сервера

{
    "ok": true,
    "result": {
        "comments": [
            {
                "comment_id": "17",
                "user_id": "425",
                "parent": "0",
                "message": "Отличный вопрос!",
                "name": "Волосатый монстр",
                "avatar": "https://image.thisorthat.ru/200/425"
            },
            {
                "comment_id": "18",
                "user_id": "221",
                "parent": "0",
                "message": "Полная ерунда",
                "name": "Умный багажник",
                "avatar": "https://image.thisorthat.ru/200/221"
            }
        ],
        "pages": {
            "count": 2,
            "offset": 0,
            "total": 18
        }
    }
}

Ответ сервера содержит список объектов comments и список настроек пагинации pages.

Описание полей вопроса

Описание полей пагинации

/getMyComments

Получает список комментариев пользователя.

Запрос

GET|POST https://api.thisorthat.ru/getMyComments

Параметры запроса

Параметры, выделенные полужирным, являются обязательными.

Пример запроса

curl --include --request GET 'https://api.thisorthat.ru/getMyComments?token=1:0994f52572ab3f9432c77615c104db9c'

Ответ сервера

{
    "ok": true,
    "result": {
        "comments": [
            {
                "comment_id": "46",
                "parent": "0",
                "message": "Отличный вопрос",
                "item_id": "89651",
                "avatar": "https://image.thisorthat.ru/100/1"
              },
              {
                "comment_id": "47",
                "parent": "0",
                "message": "Не знаю, что и сказать",
                "item_id": "89651",
                "avatar": "https://image.thisorthat.ru/100/1"
              },
              {
                "comment_id": "48",
                "parent": "0",
                "message": "Прекрасно написано",
                "item_id": "93835",
                "avatar": "https://image.thisorthat.ru/100/1"
              }
        ],
        "pages": {
          "count": 50,
          "offset": 1,
          "total": 132
        }
    }
}

Ответ сервера содержит список объектов comments и список настроек пагинации pages.

Описание полей вопроса

Описание полей пагинации

/addComment

Добавление нового комментария к вопросу.

Запрос

GET|POST https://api.thisorthat.ru/addComment

Параметры запроса

Параметры, выделенные полужирным, являются обязательными.

Пример запроса

curl --include --request POST --data 'item_id=1&message=Отличный комментарий' 'https://api.thisorthat.ru/addComment?token=1:0994f52572ab3f9432c77615c104db9c'

Ответ сервера

{
    "ok": true,
    "result": {
        "comment_id": "300",
        "user_id": "1",
        "parent": "0",
        "message": "Отличный комментарий",
        "name": "Волосатый монстр",
        "avatar": "https://image.thisorthat.ru/200/1"
    }
}

В случае ошибки клиент может отобразить на своей стороне результат поля description. Между запросами на добавление комментария должно пройти минимум 20 секунд, иначе сервер вернет ошибку.

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

/reportComment

Отправляет жалобу на комментарий.

Запрос

GET|POST https://api.thisorthat.ru/reportComment

Параметры запроса

Параметры, выделенные полужирным, являются обязательными.

Пример запроса

curl --include --request POST 'https://api.thisorthat.ru/reportComment?token=1:0994f52572ab3f9432c77615c104db9c&comment_id=1'

Ответ сервера

{
    "ok": true,
    "result": true
}

В случае удачного выполнения сервер вернет true.

/getAudit

Возвращает список из 30 вопросов для модерации, которые пользователь еще не видел.

Запрос

GET|POST https://api.thisorthat.ru/getAudit

Параметры запроса

Параметры, выделенные полужирным, являются обязательными.

Пример запроса

curl --include --request GET 'https://api.thisorthat.ru/getAudit?token=1:0994f52572ab3f9432c77615c104db9c'

Ответ сервера

{
    "ok": true,
    "result": {
        "items": [
            {
                "item_id": "1926",
                "first_text": "Остаться слепым на всю жизнь",
                "last_text": "Остаться глухим на всю жизнь"
            },
            {
                "item_id": "5043",
                "first_text": "Быть нервным",
                "last_text": "Быть ранимым"
            }
        ]
    }
}

Ответ сервера содержит список объектов items. Клиент может перемешать вопросы после получения.

Описание полей вопроса

/setAudit

Метод записывает в базу данных результат модерации для конкретного вопроса.

Запрос

GET|POST https://api.thisorthat.ru/setAudit

Параметры запроса

Параметры, выделенные полужирным, являются обязательными.

Пример запроса

curl --include --request GET 'https://api.thisorthat.ru/setAudit?token=1:0994f52572ab3f9432c77615c104db9c&item_id=1&vote=approve'

Ответ сервера

{
    "ok": true,
    "result": true
}

В случае удачного выполнения сервер вернет true.