API Документерры
Каждый портал Документерры оснащен интерфейсом REST API, позволяющим автоматизировать задачи и интегрировать документооборот в существующие бизнес-процессы.
- Базовый URL-адрес REST API
- Авторизация
- Коды статуса ответа
- Коды успеха
- Коды ошибок
- Примечание к ответам
- Примечание к справочнику по API
Базовый URL-адрес REST API
Все URL-адреса в справочной документации используют следующий базовый URL-адрес:
https://{your-portal-URL}/api/v1/
По умолчанию URL-адрес вашего портала выглядит как hedronlabs.documenterra.co, где hedronlabs — имя вашего портала. Если вы используете собственный домен, например, docs.hedronlabs.org, он используется вместо адреса по умолчанию.
Все запросы к REST API Документерры обслуживаются по протоколу HTTPS. Незашифрованный HTTP не поддерживается. Кроме того, система Документерра использует протокол TLS 1.2; любая более ранняя версия не поддерживается.
Авторизация
Большинство запросов к REST API Документерры используют базовую авторизацию, хотя некоторые запросы можно делать анонимно. Короче говоря, вы будете использовать логин своей учетной записи в системе Документерра в качестве имени пользователя, а ключ API — в качестве пароля для базовой авторизации HTTP. Поэтому обязательно используйте флаг -u (--user):
Bash (Unix Shell) |
--basic ^ |
| При авторизации вам необходимо указать свой логин и ключ API, а не пароль. |
Вы можете взять свой логин и сгенерировать ключ API в своем профиле. Инструкции смотри в разделе «Получение ключа API». Обратите внимание, что только Авторы могут генерировать ключи API.
Коды статуса ответа
Все запросы API будут возвращать определенные коды — это может быть код успеха или код ошибки. Ниже приведен список всех кодов состояния, которые может возвращать API Документерры.
Коды успеха
| 200 OK (хорошо) | Запрос выполнен успешно. Значение «успеха» зависит от метода HTTP. |
| 201 Created (создано) |
Запрос выполнен успешно, и в результате был создан новый ресурс. |
| 204 No Content (нет содержимого) |
Запрос выполнен успешно. |
Коды ошибок
API должен выдать сообщение с кодом ошибки, который подскажет, что пошло не так. Кроме того, вы можете ознакомиться с инструкциями по устранению ошибок в разделе Устранение неполадок API. Если это не помогло или система выдает непонятное сообщение об ошибке, обратитесь по адресу support@documenterra.com и предоставьте подробную информацию о ситуации.
| 400 Bad Request (некорректный запрос) |
Данные в вашем запросе неверны, и сервер не может или отказывается их обрабатывать, например, неправильный синтаксис запроса, неправильный фрейм сообщения запроса и т.д. |
| 401 Unauthorized (не авторизован) |
Логин или ключ API недействительны, информация для входа не указана, ваша учетная запись отключена или HTTP-заголовок авторизации вашего запроса поврежден — подробности смотри в тексте ответа. Убедитесь, что вместо ключа API не указан пароль.
|
| 403 Forbidden (запрещено) |
У вас нет разрешения работать с API или выполнять запрошенное действие. Подробности смотри в ответе на запрос. |
| 404 Not Found (не найдено) |
Ресурс, который вы ищете, не найден. Это может произойти, если указанный вами URL-адрес недействителен или ресурс, на который вы ссылаетесь, не существует. |
| 409 Conflict (конфликт) |
Действие, которое вы попытались выполнить, привело к конфликту данных, что обычно означает дублирование идентификаторов (например, создание пользователя с уже существующим именем). Подробности смотри в ответе на запрос. |
| 500 Internal Server Error (внутренняя ошибка сервера) |
При обработке запроса что-то пошло не так. Подробности смотри в ответе на запрос. |
| 501 Not Implemented (не реализовано) |
Вы попытались выполнить какое-либо действие, которое в настоящее время не поддерживается API. Если вы получили данный код ответа, свяжитесь с нами и сообщите, что вы пытаетесь сделать. |
Тело сообщения об ошибке
В случае ошибок тело ответа HTTP всегда содержит объект JSON со следующими полями:
| Поле | Описание |
|---|---|
| Message (сообщение) | Cообщение об исключении с подробностями. |
| ExceptionType (тип исключения) | Тип исключения. |
| ExceptionDetail (Сведения об исключении) | Предназначено для использования в будущем. |
| StackTrace (стек-трейс) | Предназначено для использования в будущем. |
Примечание к ответам
Все ответы имеют несколько общих черт.
- Все методы POST выдают местоположение соответствующего ресурса (страницы, элемента Дерева страниц и т.д.) в заголовке Location (местоположение).
- Все методы PATCH выдают полный обновленный ресурс, как если бы вы впоследствии запустили запрос GET.
Примечание к справочнику по API
Ниже приведена информация, которую вам следует знать, прежде чем обращаться к справочнику API Документерры.
Все примеры из справочника включают только специальные флаги/параметры для cURL и не включают общие флаги, определяющие файл CA bundle и данные аутентификации. Убедитесь, что вы включили их во все запросы: Bash (Unix Shell)--user "login:api-key" ^
--cacert comodo.ca-bundle ^- В справочнике приведены примеры запросов API с использованием утилиты cURL. Важно отметить, что в примерах используется параметр командной строки --cacert. В нем указано имя файла CA Bundle — файла с корневыми и промежуточными сертификатами центра сертификации, выдавшего SSL-сертификат целевой конечной точки. cURL использует данный файл для проверки SSL-сертификата конечной точки. Данный тип файла обычно доступен на веб-сайте сертификационного центра, и его можно скачать.
Если вы используете доменное имя по умолчанию {portal-name}.documenterra.co, вы можете использовать этот файл CA Bundle. Если вы используете собственное доменное имя с собственным сертификатом SSL, запросите файл CA Bundle в своем центре сертификации. - По умолчанию параметры считаются обязательными. Все необязательные параметры помечены как [optional] (опционально) или [deprecated] (исключено).
Узнать подробнее об API REST Документерры можно здесь: