API: Общие сведения

Архитектура

WorkPoint реализует OData v4 API доступный на конечной точке https://api.workpoint.app.

Спецификация OData доступна на официальном сайте — https://www.odata.org. Если вы незнакомы с этим протоколом, то рекомендуем до разработки интеграции освоить, как минимум, базовые понятия — https://www.odata.org/getting-started/understand-odata-in-6-steps.

Для аутентификации используется отдельный OAuth 2.0 сервис доступный по адресу https://passport.workpoint.app.

В большинстве случаев любая сущность управляется стандартными запросами (POST, PUT, DELETE, GET, PATCH). Поддерживается язык запросов OData. Для отдельных сущностей доступны специализированные действия и функции. Веб-клиент использует этот же API, таким образом его обращения к API могут послужить примером.

Полное описание метаданных — https://api.workpoint.app/$metadata.

Тестирование и отладка

Рекомендуется тестировать обращения к WorkPoint отдельно, например с помощью Postman. Это позволит отделить потенциальные проблемы с использованием API, от логики и окружения конкретного интеграционного механизма и, в случае обращения в поддержку, значительно ускорит время ответа.

В случае успешного выполнения операции возвращается ответ с HTTP кодом 200-204.

В случае ошибки доступа (чаще всего в виду неправильного Bearer токена) возвращается ответ с HTTP кодом 401.

В случае ошибки в бизнес-логике возвращается ответ с HTTP кодом 500 и телом в формате: 

{
    "error": {
        "code": "error code",
        "message": "error description",        
        "details": {}
    }
}