Руководство по разработке

Навигатор по разделу:

1. Rest API Avanpost DS

Полная документация по всем endpoint'ам реализована с использованием Swagger UI и доступна после развертывания контроллера домена Avanpost DS по адресу: 

http://[IP-адрес КД Avanpost DS]:4008/docs/

Внимание!

Для просмотра документации в Swagger требуется ее опубликовать с помощью веб-сервера. Подробнее о публикации с помощью Nginx см. статью "4.6.2.2. Публикация Swagger".

2. Примеры запросов Rest API Avanpost DS

Ниже представлены примеры использования наиболее распространенных запросов.

2.1. Получение токена авторизации

Endpoint:
POST /api/v1/login

Параметры запроса (JSON body):

ПараметрЗначение
userpasswordПароль пользователя
cnЛогин пользователя
Пример запроса:
curl -c cookie-jar.txt -X POST \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "userpassword":"Avanp0st",
  "cn":"Administrator"}' \
  http://10.5.5.7:4008/api/v1/login
  • Токен авторизации сохраняется в файл "cookie-jar.txt".
  • Для последующих запросов требуется использовать файл "cookie-jar.txt" с флагом "-b".

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

Endpoint:
POST /api/v1/users

Параметры запроса (JSON body):

ПараметрЗначение
cnЛогин пользователя
givennameИмя
surnameФамилия
mailПочта
userPasswordПароль пользователя
requirepasswordchange

Значение "true", если требуется смена пароля.

Значение "false" — в обратном случае.

passwordneverexpires

Значение "true", если пароль бессрочный.

Значение "false" — в обратном случае.

Пример запроса:
curl -b cookie-jar.txt -X POST \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "cn":"stepanov",
  "givenname":"Александр",
  "surname":"Степанов",
  "mail":"stepanov@avanpost.local",
  "userPassword":"Avanp0st",
  "requirepasswordchange":false,
  "passwordneverexpires":true
  }' \
  http://10.5.5.7:4008/api/v1/users
Результат выполнения:
{"uid":"d5bbae16-ddc0-4a15-9f59-032cd40001a7","dn":"cn=stepanov123,ou=users,dc=avanpost,dc=local","attributes":null}

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

Endpoint:
PUT /api/v1/users/{uid}

Параметры запроса (JSON body):

ПараметрЗначение
uidИдентификатор пользователя, полученный при создании (указывается в URL)
mailПочта
givennameИмя
surnameФамилия
cnЛогин пользователя
Пример запроса:
curl -b cookie-jar.txt -X PUT \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "mail": "new_email@domain.com",
    "givenname": "Иван",
    "surname": "Иванов",
    "userPassword": "NewPassword123",
  }' \
  http://10.5.5.7:4008/api/v1/users/d5bbae16-ddc0-4a15-9f59-032cd40001a7

2.4. Создание группы

Endpoint:
POST /api/v1/groups

Параметры запроса (JSON body):

ПараметрЗначение
cnНазвание группы (обязательно)

description

Описание группы (опционально)
Пример запроса:
curl -b cookie-jar.txt -X POST \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "cn": "idm_admins",
    "description": "Администраторы IDM"
  }' \
  http://10.5.5.7:4008/api/v1/groups
Результат выполнения:
{"uid":"705a8b28-43c4-4f74-a005-98835a913b64","dn":"cn=idm_admins,ou=groups,dc=avanpost,dc=local","attributes":null}

2.5. Добавление пользователей в группу

Endpoint:
PUT /api/v1/groups/{groupUID}/members-add-uids

Параметры запроса (JSON body):

ПараметрЗначение
groupUIDИдентификатор группы (указывается в URL)
memberМассив UID пользователей для добавления
Пример запроса:
curl -b cookie-jar.txt -X PUT \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "member": [
      "d5bbae16-ddc0-4a15-9f59-032cd40001a7"
    ]
  }' \
  http://10.5.5.7:4008/api/v1/groups/705a8b28-43c4-4f74-a005-98835a913b64/members-add-uids

2.6. Создание подразделения

Endpoint:
POST /api/v1/hierarchy/add

Параметры запроса (JSON body):

ПараметрЗначение
NewObjectNameНазвание создаваемого подразделения (обязательно)
BaseObjectDN родительского объекта (обязательно)
Attributes

Массив атрибутов подразделения (обязательно)

Параметр Значение
type_Тип атрибута
valsЗначения атрибута

Обязательные атрибуты:

АтрибутЗначение
objectclassДолжен содержать "top" и "organizationalUnit"
ouНазвание подразделения (должен совпадать с параметром "NewObjectName")
Пример запроса:
curl -b cookie-jar.txt -X POST \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "NewObjectName": "Отдел маркетинга",
    "BaseObject": "ou=users,dc=avanpost,dc=local",
    "Attributes": [
      {
        "type_": "objectclass",
        "vals": ["top", "organizationalUnit"]
      },
      {
        "type_": "ou",
        "vals": ["Отдел маркетинга"]
      }
    ]
  }' \
  http://10.5.5.7:4008/api/v1/hierarchy/add

2.7. Перемещение объекта в подразделение

Endpoint:
POST /api/v1/hierarchy/move

Параметры запроса (JSON body):

ПараметрЗначение
entryТекущий Distinguished Name (DN) перемещаемого объекта
newparentDN целевого родительского подразделения
Пример запроса:
curl -b cookie-jar.txt -X POST \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "entry": "cn=tst-rest-api-01,ou=hosts,dc=avanpost,dc=local",
    "newparent": "ou=Маркетинг,ou=Тест OU,dc=avanpost,dc=local"
  }' \
  http://10.5.5.7:4008/api/v1/hierarchy/move

Обсуждение