Granatum API

Опубликовано August 23, 2021

Granatum Solutions – облачный сервис, объединяющий инструменты для интерактивного общения и групповой работы с методологией эффективного взаимодействия в онлайне. Мы предоставляем возможность самостоятельно создать интеграцию вашей системы с granatum, а также получать данные об активности пользователей и обрабатывать их на своей стороне.

Как получить ключ

API открывается только по персональному запросу. После открытия доступа к API, вам будет предоставлен секретный ключ. Для получения дополнительной информации обратитесь к клиент-менеджеру: info@granatum.solutions

Авторизация

Для авторизации необходимо посылать ключ API с каждым запросом в заголовке «Authorization».

Authorization: {api_key}

Запрос и ответ передается в формате JSON.

OpenAPI спецификация

OpenAPI представляет собой формализованную спецификацию и полноценный фреймворк для описания, создания, использования и визуализации веб-сервисов.
Swagger-UI
openapi.yaml

Действия с пользователями

Создание нового пользователя

Запрос

POST /registration

{
  "email": "string",
  "name": "string",
  "password": "string",  
  "externalId": "string",
  "projectIds": [  
    "string"
  ],
  "additionalProperties": {  
    "key": "value"
  },
  "coursePermissions": {  
    "courseId": "USER",
    "anotherCourseId": "COURSE_ADMIN"
  }
}

Ответ

{
  "id": "6052107bcf35a141992f041c",
  "email": "string",
  "name": "string"
}

Поля «email» и «name» обязательны и не могут быть пусты, остальные – опциональны.

Если поле password == null, пользователь будет создан со стандартным паролем «granatum», при первом входе ему будет предложено сменить его. Пароль должен быть не менее 8 символов, содержать как минимум одну букву, цифру и спецсимвол. В пароле допускаются только буквы латинского алфавита.

В поле «externalId» можно записать id пользователя из вашей системы.

«projectIds» – это опциональное поле, содержит id пространств, к которым будет предоставлен доступ. При отсутствии этого поля, доступ будет предоставлен ко всем вашим пространствам.

Дополнительные поля можно послать внутри объекта «additionalProperties». Там могут содержаться любые поля, они будут сохранены вместе с пользователем.

«coursePermissions» – список id проектов, куда пользователям нужно предоставить доступ. Заполнять не обязательно. Для каждого id проекта нужно указать роль человека в нём: обычный пользователь (USER) или админ проекта COURSE_ADMIN).

Изменить данные пользователя

Запрос

PATCH /account/{id}

{
  "name": "string",
  "projectIds": [
    "string"
  ],
  "externalId": "string",
  "additionalProperties": {
    "key": "value"
  }
}

Ответ

{
  "id": "6052107bcf35a141992f041c",
  "email": "string",
  "name": "string",
  "externalId": "string",
  "additionalProperties": {
    "key": "value"
  }
}

При обновлении «projectIds» нужно передавать все проекты, к которым пользователь должен иметь доступ. Например, пользователь имеет доступ к проектам A и C, и вам нужно предоставить доступ к проекту B и забрать доступ к проекту C. Тогда поле «projectIds» будет выглядеть так: [“A”, “B”].

Удаление пользователя

Запрос

DELETE /account/{id}

Ответ

200 OK

Данный запрос удаляет пользователя совсем из системы.

Изменение пароля

Запрос

POST /reset

{
  "id": "userID",
  "password": "string"
}

Ответ

{
  "id": "userID"
}

Если поле password == null, пользователь будет создан со стандартным паролем «granatum», при следующем входе ему будет предложено сменить его. Пароль должен быть не менее 8 символов, содержать как минимум одну букву, цифру и спецсимвол. В пароле допускаются только буквы латинского алфавита.

Доступы

Предоставление доступа к проектам

Запрос

POST /courses/{id}/users

{
  "accountIds": [
    "userID1",
    "userID2"
  ],
  "role": "USER"
}

Ответ

200 OK

В поле «role» можно указать USER (обычный пользователь) и COURSE_ADMIN (администратор проекта).

Удаление доступа пользователей к проекту

Запрос

DELETE /courses/{id}/users?id={userID1}&role={USER}

Ответ

200 OK

Можно передать ID одного юзера или нескольких. В «role» можно передать USER или COURSE_ADMIN в зависимости от того, какой доступ юзерам вы хотите удалить.

Получить инвайт в сессию

Запрос

GET /sessions/{id}/invite

Ответ

{
  "invite": "string"
}

Данный запрос возвращает ссылку-инвайт на сессию, по которой пользователи могут самостоятельно на неё зарегистрироваться.

Статистика

Получить список всех пользователей пространства

Запрос

GET /users

Ответ

[
  {
    "email": "string",
    "externalId": "string",
    "active": true,
    "role": "USER",
    "additionalProperties": {}
  }
]

Запрос возвращает всех ваших пользователей, включая всех администраторов. Если по ключу вы имеете доступ к нескольким пространствам, вернётся список пользователей всех пространств.

Получить список всех проектов пространства

Запрос

GET /courses

Ответ

[
  {
    "id": "string",
    "name": "string"
  }
]

Запрос возвращает все ваши проекты. Если по ключу вы имеете доступ к нескольким пространствам, вернётся список проектов всех пространств.

Прогресс пользователей проекта

Запрос

GET /courses/{id}/progress

Ответ

[
  {
    "email": "string",
    "sessions": [
      {
        "id": "string",
        "name": "string",
        "averageScore": 0
      }
    ]
  }
]

Запрос возвращает список всех пользователей, которые имеют доступ к проекту, и суммарные баллы по всем тестам, которые они набрали в рамках этого проекта. ID проекта должен быть строго один.

Получить список сессий проекта

Запрос

GET /courses/{id}/sessions

Ответ

[
  {
    "id": "string",
    "name": "string",
    "description": "string",
    "courseId": "string",
    "startDate": "2020-10-19T17:49:45.632Z"
  }
]

Запрос возвращает список всех сессий проекта. ID проекта должен быть строго один.

Получить список пользователей проекта

Запрос

GET /courses/{id}/users?page={pageNumber}&size={pageSize}

Ответ

{
  "content": [
    {
      "id": "string",
      "email": "string",
      "name": "string",
      "active": true,
      "role": "string"
    }
  ],
  "pageable": {
    "sort": {
      "sorted": false,
      "unsorted": true,
      "empty": true
    },
    "pageNumber": 0,
    "pageSize": 0,
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "last": true,
  "totalElements": 0,
  "totalPages": 0,
  "first": true,
  "number": 0,
  "sort": {
    "sorted": false,
    "unsorted": true,
    "empty": true
  },
  "numberOfElements": 0,
  "size": 0,
  "empty": false
}

Запрос возвращает список всех пользователей, которые имеют доступ к проекту. ID проекта должен быть строго один. Если “active” == true, пользователь хотя бы раз заходил хотя в одну сессию пространства в текущем отчетном периоде.

Список пользователей возвращается постранично, где pageNumber – номер страницы, pageSize – количество записей на одной странице. Максимум на одно странице – 100 записей.

Результаты прохождения тестов в сессии

Запрос

GET /sessions/{id}/results?page={pageNumber}&size={pageSize}

Ответ

{
  "content": [
    {
      "email": "email",
      "attempts": 0,
      "score": 0
    }
  ],
  "pageable": {
    "sort": {
      "sorted": false,
      "unsorted": true,
      "empty": true
    },
    "pageNumber": 0,
    "pageSize": 0,
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "totalElements": 0,
  "last": true,
  "totalPages": 0,
  "first": true,
  "sort": {
    "sorted": false,
    "unsorted": true,
    "empty": true
  },
  "number": 0,
  "numberOfElements": 0,
  "size": 0,
  "empty": false
}

Запрос возвращает список всех пользователей, которые проходили тесты в сессии. В«attempts» указывается количество попыток, в «score» – суммарное количество баллов.

Список пользователей возвращается постранично, где pageNumber – номер страницы, pageSize – количество записей на одной странице. Максимум на одно странице – 100 записей.

Получить список пользователей сессии

Запрос

GET /sessions/{id}/users

Ответ

[
  {
    "email": "string",
    "externalId": "string",
    "active": true,
    "role": "USER",
    "additionalProperties": {}
  }
]

Запрос возвращает список всех пользователей, которые хотя бы раз заходили в сессию.

Действия с сессией

Создание нового прохождения в сессии

Запрос

POST /sessions/{id}/passing

Ответ

200 OK

Запрос создаёт новое прохождение в сессии. Будьте внимательны, при создании нового прохождения все стикеры, результаты тестов и чаты удаляются с сессии и уходят в историю.

Копирование сессии

Запрос

POST /sessions/copy

{
  "courseId": "string",
  "sessionIds": [
    {
      "sessionId": "string",
      "name": "string"
    }
  ]
}

Ответ

[
  {
    "id": "string",
    "name": "string",
    "description": "string",
    "courseId": "string",
    "startDate": "2020-10-19T17:49:45.632Z"
  }
]

В «courseId» указывается проект, куда необходимо скопировать сессию, в «sessionId» – сессию, которую надо скопировать, в «name» – какое имя должно быть у скопированной сессии.

Удаление сессии

Запрос

DELETE /sessions?id={sessionID}

Ответ

200 OK

Теги :