Введение в RESTful API

Общая информация

UseResponse - это комплексная платформа для оказания поддержки клиентам. Но если вы используете другие системы для проектного управления, выставления счетов, хостинга, вы можете улучшить свой опыт работы с клиентами путем интеграции нашего Restful API в вашу платформу.


При формировании запросов RESTful API вы должны быть готовы к обработке ответов в виде HTTP-кодов.


Основы API

С помощью API UseResponse вы можете использовать следующие команды REST через http с помощью json: POST, GET, PUT, DELETE.

Все запросы должны выполняться на вашей платформе, предпочтительно с использованием протокола https. Обязательно используйте cURL для выполнения запросов, SDK или из вашей командной строки.

Вот, как мы обращаемся к конкретному ресурсу:

GET /api/3.0/users/search.json

Это значит, что перед отправкой запроса вам необходимо добавить собственный домен, как на примере ниже:

https://mydomain.useresponse.com/api/3.0/users/search.json

Вы можете скопировать имя домена из настроек API, которые расположены в Параметрах пользовательского профиля.

Все запросы выполняются в формате json. Примеры запросов и ответов представлены в каждом разделе документации.

Аутентификация и ключи безопасности

Чтобы выполнить любой запрос к API UseResponse, необходимо авторизовать ваши запросы, предоставив действительный ключ API. Если доступен гостевой API, запросы можно выполнять без предоставления какого-либо ключа api.

Управление основными настройками API осуществляется в разделе Администрирование » Система » API, где вы можете отключить api, использовать гостевой api, а также установить права доступа для определенных администраторов и агентов по использованию api.

Чтобы получить какие-либо данные, вы должны обладать соответствующими правами доступа, которые определяются вашей ролью в системе. Например, если вы будете использовать гостевой api, вы получите только ту информацию, которая доступна в сообществе для гостя.

Ключ API можно скопировать и обновить в Профиле пользователя - Параметры - Настройки API. Вы также можете отключить ключи для определенных пользователей.

Пример GET запроса с API ключом с использованием cURL
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -X GET https://domain.com/api/3.0/users/search.json?apiKey=<your_api_key>&role=user

Пагинация

По умолчанию количество отображаемых записей на странице равно 50. Вы можете изменить это количество с использованием COUNT параметра.

GET /api/3.0/users/search.json?page=1&count=30

Ответ на запрос будет содержать общее количество объектов, количество объектов на странице, количество страниц (первая, последующая, последняя).

Коды ответов

Коды, возвращаемые API UseResponse, предоставляют сведения о статусе вашего запроса в случае возникновения каких-либо проблем:

Код Статус Описание
200 OK Успешный запрос.
204 No Content   Запрос успешный, но результаты не найдены
400 Bad Request Недействительный запрос и/или параметры запроса
401 Bad Authentication Data Для получения данных требуется аутентификация. Недействительный ключ API или неверный формат ключа API
403 Forbidden API запрос запрещен из-за отсутствия прав доступа
404 Not Found Когда запрашиваемый ресурс не найден (ресурс не существует или возвращается 401/403 ошибка безопасности). Например, API запрос был сделан на недействительный URL.
405 Method Not Allowed Запрашиваемый метод запрещен. Например, API запрос был сформирован с использованием DELETE метода, но ресурс принимает только GET или POST методы.
409 Conflict Возникает всякий раз, когда выполняется запрос, например, при создании дублирующихся записей.
500 Internal Server Error Ошибка на стороне сервера.
503 Service Unavailable Интерфейс API недоступен или отключен.

Клиенты API - SDK

API клиент на PHP поможет внедрить API эффективнее и оптимизировать работу с данными, используя готовые методы для работы с заявками, темами, пользователями и пр.

Клиент может быть добавлен с использованием composer или через самостоятельный загрузчик.

Архив также включает примеры формирования типичных запросов для понимания того, как это работает, которые расположены в папке /src/Sdk/Examples.

Была ли статья полезной?