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 могут послужить примером.

Важно! WorkPoint — развиваемая система. Версионирования API нет. Мы прилагаем все усилия для недопущения критических изменений, если таковые есть — предупреждаем минимум за 14 дней, но при разработке интеграций необходимо быть готовым поддерживать её актуальность.

Поля навигации

Сущности могут содержать поля навигации, например User содержит свойство Department. Такое поле всегда идет в паре с ключом, в данном случае departmentId.

В описании сущностей мы опускаем упоминание о наличии ключа навигации.

Поля навигации можно «раскрывать» при запросе:

[GET] https://api.workpoint.app/odata/Users(a5e16802-23d9-48be-99bb-02d9e34c7409)?$expand=department($select=name),$select=name,departmentId  
Response: 
{
   "name": "Иван Агафонов",
   "departmentId": "9468cd5c-ea04-4adb-a1d7-94b6b910ab2e"
   "department": 
   {
      "name": "Департамент корпоративного аудита 02"
   }
}

Для обновления полей навигации необходимо использовать их ключи, например:

[PATCH] https://api.workpoint.app/odata/Users(a5e16802-23d9-48be-99bb-02d9e34c7409)  
Body: 
{   
   "departmentId": "9468cd5c-ea04-4adb-a1d7-94b6b910ab2e"   
}

Обработка ошибок

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

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

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

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

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

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