|
|
|
# Общие положения
|
|
|
|
|
|
|
|
## Введение
|
|
|
|
|
|
|
|
OpenAPI Skillaz предоставляет эффективные средства взаимодействия с различными сущностями системы, включая кандидатов, вакансии, заявки, организационные единицы, справочники и прочее.
|
|
|
|
|
|
|
|
## Протокол и методы
|
|
|
|
|
|
|
|
Основным протоколом взаимодействия является HTTPS.
|
|
|
|
|
|
|
|
Поддерживаются стандартные методы HTTP: GET, POST, PUT, DELETE и PATCH.
|
|
|
|
|
|
|
|
- `GET`: Используется для получения данных.
|
|
|
|
- `POST`: Применяется для создания новых записей и получения данных по фильтрам. В массовых методах создания/обновления объектов так же применяется для полного обновления данных.
|
|
|
|
- `PUT`: Выполняет полное обновление данных. Для некоторых объектов может также использоваться для частичного обновления ( как аналог PATCH). Детали применения следует изучать в документации к конкретному методу.
|
|
|
|
- `PATCH` : Выполняет частичное обновление данных.
|
|
|
|
- `DELETE`: Применяется для удаления(архивации) сущностей.
|
|
|
|
|
|
|
|
## Аутентификация (Как получить токен?)
|
|
|
|
|
|
|
|
Для аутентификации и авторизации используются Bearer токены. Токен передается во все отправляемые запросы к OpenAPI Skillaz как header-параметр:
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
--header 'Authorization: Bearer PZoruHE3iQrXIYygSu7804GB2VAxIAo2ZOETlutvkF1=' \
|
|
|
|
```
|
|
|
|
|
|
|
|
Уникальный Bearer-токен выдаётся для каждой из интегрируемых систем.
|
|
|
|
|
|
|
|
Чтобы получить Bearer токен обратитесь с Ответственному сотруднику со стороны Skillaz. При запросе Bearer токена укажите название интегрируемой системы . Именно с этим названием будут записываться изменения в системе и именно оно будет отображаться в истории изменения объектов (кандидатов, заявок и т.п) в системе.
|
|
|
|
|
|
|
|
## Разделение адресов для окружений разработки и продакшна
|
|
|
|
|
|
|
|
Важным аспектом является различие адресов endpoint-ов для окружений разработки (dev) и продакшна (prod). Bearer токен на каждую из сред запрашивается и выдается отдельно. В адресах будет меняться только начало адреса, конечные адреса endpoint-ов (начинающиеся с `/open-api/` )между окружениями неизменны.
|
|
|
|
|
|
|
|
На dev-окружении могут быть внесены изменения, отсутствующие на продакшене. Данное описание касается окружения prod.
|
|
|
|
|
|
|
|
> Пример: `https://api.skillaz.ru/open-api/objects/candidates` - prod
|
|
|
|
>
|
|
|
|
> `https://api-feature-configurator.dev.skillaz.ru/open-api/objects/candidates` - тот же endpoint в окружении dev на фиче конфигуратора
|
|
|
|
|
|
|
|
## Безопасное взаимодействие с API
|
|
|
|
|
|
|
|
Наш API принимает запросы только из backend-приложений. Запрещено обращение из клиентских приложений, таких как JavaScript. При попытке такого обращения токены будут отозваны в целях безопасности. Используйте серверный backend или шину для взаимодействия с нашим API
|
|
|
|
|
|
|
|
## Как добавить подписку на веб-хуки
|
|
|
|
|
|
|
|
Подписка на веб-хуки администрируется через интерфейс системы. Для добавлении подписки обратитесь к Ответственному сотруднику со стороны Skillaz.
|
|
|
|
|
|
|
|
## Ответственные сотрудники со стороны Skillaz
|
|
|
|
|
|
|
|
Ответственные сотрудники со стороны Skillaz зависят от стадии проекта внедрения:
|
|
|
|
|
|
|
|
- для компании в процессе внедрения проекта - менеджер проекта
|
|
|
|
|
|
|
|
- для компаний завершивших внедрение и перешедших на аккаунтинг - аккаунт-менеджер
|
|
|
|
|
|
|
|
- при предоставлении демо-доступа - пресейл-менеджер
|
|
|
|
|
|
|
|
|
|
|
|
## Работа с частичной передачей данных (Пагинация и курсор)
|
|
|
|
|
|
|
|
Некоторые запросы в OpenAPI могут возвращать объемные наборы данных, которые разделены на части для оптимизации передачи. Для эффективной обработки таких случаев предусмотрены два механизма: *пагинация* и *курсоры.*
|
|
|
|
|
|
|
|
### **Пагинация:**
|
|
|
|
|
|
|
|
- Пагинация представляет собой механизм разбиения большого набора данных на отдельные "страницы" с ограниченным количеством элементов.
|
|
|
|
|
|
|
|
- *Использование:* В параметрах запроса указывается размер страницы (`PageSize`) и номер текущей страницы (`CurrentPage`). Ответ на запрос с пагинацией включает номер следующей страницы (`NextPage`), общее количество страниц (`TotalPages`), и общее количество результатов (`TotalItems`).
|
|
|
|
|
|
|
|
- *Особенности использования и ограничения:*
|
|
|
|
|
|
|
|
- Нумерация страниц идёт с 1
|
|
|
|
|
|
|
|
- Максимальный размер страницы(`PageSize`) - 10000.
|
|
|
|
|
|
|
|
- Значение по умолчанию, если не передавать параметры - `"PageSize":30` **,** `"CurrentPage":0`**.**
|
|
|
|
|
|
|
|
- `NextPage` имеет значение `null` в ответе на запрос в том случае, когда страница - последняя
|
|
|
|
|
|
|
|
- можно обращаться к любой странице, но если она не существует - массив `Items` будет пустой . Исключение - если передать страницу **`CurrentPage:0`** - тогда вернется страница с номером 1
|
|
|
|
|
|
|
|
- При установке слишком большого значения Максимального размера страницы `PageSize` возможно возникновения ошибки о превышении максимального размера ответа на запрос (Maximum response size reached)
|
|
|
|
|
|
|
|
- При установке значения Максимального размера страницы\*\*`PageSize`\*\*>10000 возможно возникновение ошибки 500 на запрос и деталями запроса вида:
|
|
|
|
|
|
|
|
```json
|
|
|
|
"Detail": "Elasticsearch.Net.ElasticsearchClientException: Request failed to execute. ...
|
|
|
|
```
|
|
|
|
|
|
|
|
т.к. ограничение в 10000 элементов на уровне базы данных.
|
|
|
|
|
|
|
|
|
|
|
|
### **Курсор:**
|
|
|
|
|
|
|
|
- Курсоры используются для маркировки и возврата больших объемов данных. Каждый запрос возвращает токен (**`NextPageCursor`**), который используется в следующем запросе как **`QUERY PARAMETER`**.
|
|
|
|
|
|
|
|
- *Использование:* Если количество элементов в ответе на запрос превышает установленный предел ( в большинстве методов - 10000 элементов), в ответе генерируруется значение **`NextPageCursor`**. Этот токен передается в следующем запросе для получения следующей порции данных как PATH PARAMETER “Токен для получения следующих результатов” **`cursor`** (string)
|
|
|
|
|
|
|
|
- *Особенности использования и ограничения:*
|
|
|
|
|
|
|
|
- **`NextPageCursor`** имеет значение **`null`** в ответе на запрос в том случае, когда страница - последняя (или в базе данных меньше 10000 элементов)
|
|
|
|
|
|
|
|
- страницы выдачи формируются поэтапно ( т.е. нельзя запросить сразу последнюю страницу - надо выгрузить предварительно все предшествующие)
|
|
|
|
|
|
|
|
|
|
|
|
## Экранирование
|
|
|
|
|
|
|
|
В JSON запросах кавычки экранируются обратным слешем (**`\`**). Например:
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Name": "ООО \"СКИЛАЗ\""
|
|
|
|
}
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
## Ограничения
|
|
|
|
|
|
|
|
### `String`
|
|
|
|
|
|
|
|
- если `string` используется как параметр запроса - можно передать строку любой длины
|
|
|
|
- в ответах на запросы так же может быть строка любой длины
|
|
|
|
- string так же может использоваться в параметрах body запросов для выпадающих списков - в таком случае необходимо передавать id элемента выпадающего списка
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
на input - 5 или 10 Мб, кроме методов массовых - там 500Мб
|
|
|
|
на output - ограничений нет
|
|
|
|
|
|
|
|
в String можно передать строку любой длины
|
|
|
|
|
|
|
|
## Дата и время
|
|
|
|
|
|
|
|
Мы используем формат ISO 8601. В ответах на запросы данные касающиеся даты и времени всегда будут возвращены относительно UTC+0.
|
|
|
|
|
|
|
|
Примеры данных :
|
|
|
|
|
|
|
|
- `2023-12-26T16:12:00Z` - 26 декабря 2023 года, 16 часов 12 минут по всемирному координированному времени (UTC)
|
|
|
|
- `2024-01-31T12:00:00Z` - 31 января 2024 года, 12 часов дня по UTC+0
|
|
|
|
- `0001-01-01T12:00:00Z`\- 12:00 по UTC . Так будут передаваться данные по полям с типом данных "Время"
|
|
|
|
|
|
|
|
## Ошибки
|
|
|
|
|
|
|
|
(не написано)
|
|
|
|
415 - ошибка в Body запроса, например
|
|
|
|
|
|
|
|
```
|
|
|
|
{
|
|
|
|
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.13",
|
|
|
|
"title": "Unsupported Media Type",
|
|
|
|
"status": 415,
|
|
|
|
"traceId": "00-6654afd6c53faf4a5cf99e9ac890fbe4-f395389904c7d7fd-01"
|
|
|
|
}
|
|
|
|
``` |
|
|
\ No newline at end of file |
