Б.1 Общие сведения о программном интерфейсе ЕСИА

В рамках развития ЕСИА реализован прикладной программный интерфейс на базе архитектурного стиля "Representational State Transfer" (REST). Он позволяет интегрированным с ЕСИА информационным системам получать доступ к хранящимся в ЕСИА ресурсам, т.е. данным (например, о пользователях или других информационных системах), а также выполнять ряд операций.

Вызов прикладного программного интерфейса возможен только теми интегрированными с ЕСИА системами, которые имеют на это соответствующие полномочия. Контроль доступа к ресурсам ЕСИА осуществляет сервис авторизации ЕСИА, реализующий модель контроля доступа, основанную на спецификациях OAuth 2.0 (см. Приложение В).

Для обозначения ресурсов используются специальные идентификаторы. Сами ресурсы организованы иерархически, уровни разделены косой чертой - "/". Ресурсы более "низкого" уровня являются составными частями "родительского уровня":

В ЕСИА используется два типа ресурсов:

- документ содержит информацию об отдельном объекте в базе данных, который характеризуется некоторыми полями и значениями. Например, при доступе к документу об организации сервис возвращает наименование организации, ее тип, ОГРН и др. Кроме того, в документе могут содержаться ссылки на связанные ресурсы: так, в документе об организации размещаются указатели на ресурсы (документы) по ее сотрудникам;

- коллекция представляет собой список некоторых ресурсов, например, документов. Перечень организаций, сотрудников отдельной организации - примеры коллекций. Ресурсы, которые включены в коллекцию, снабжены собственными идентификаторами (uri). Обычно для обозначения коллекции используются множественные существительные (orgs, sbjs и др.).

Для вызова сервиса ЕСИА, позволяющего получить доступ к защищенному ресурсу, система-клиент должна направить в https-адрес программного интерфейса ЕСИА запрос. Для этого (в зависимости от типа запроса) используются методы GET или POST. В каждом запросе должен быть указан идентификатор ресурса, к которому запрашивается доступ. Кроме того, в запрос на вызов REST-API должен быть добавлен следующий header:

Authorization: Bearer <access token>

<access token> - маркер доступа, предварительно полученный у сервиса авторизации ЕСИА. Срок действия маркера доступа различен для каждой информационной системы и настраивается Администратором в Технологическом портале ЕСИА. Он не должен истечь на момент вызова. Маркер доступа должен быть выдан системе-клиенту на <scope>, позволяющий получить запрашиваемый защищенный ресурс. Пример запроса на получение сведений об организации с идентификатором 1000000000:

В случае успешной проверки запроса программный интерфейс возвращает данные о защищенном ресурсе. При невозможности выполнить запрос возвращается код ошибки.

При вызове сервиса могут быть заданы параметры запроса (query), которые оформляются стандартным способом. Следующий запрос позволит получить первые 15 организаций из соответствующей коллекции orgs:

При вызове сервиса может быть указана конкретная схема предоставления данных об объекте. Для этого необходимо дать ссылку на соответствующую схему в заголовке запроса (с помощью ACCEPT). Например:

Данный запрос позволяет получить сведения о пользователе с идентификатором 402, сформированные согласно схеме Person-1. Это означает, что по мере развития ЕСИА может быть изменен передаваемый атрибутный состав данных о пользователе, в результате чего появляются новые схемы - Person-2, Person-3 и т.д. В связи с этим для получения неизменного состава атрибутов рекомендуется в запросе указывать конкретную схему. Если в качестве схемы указана схема /model/prn/Person без явного указания версии, то возвращается последняя версия. Если схема не указана вообще, то также возвращается последняя версия схемы.

В ответе на корректный запрос выдается JSON-документ, который представляет собой набор пар ключ/значение или массив значений. В заголовке (headers) ответа содержатся следующие данные:

1. Ссылки (links) на связанные ресурсы. Например, если в запросе указан ресурс с данными конкретного пользователя (prns/402), то ссылки будут содержать ресурсы с его контактными данными, документами, адресами, транспортными средствами, а также на "родительский" ресурс с перечнем всех пользователей в системе.

2. Тип предоставляемых данных (Content-Type) с указанием схемы предоставляемых данных. Например, если запрашиваются данные о пользователе в схеме Person-1, то будет указано следующее значение: Content-Type: [application/json; q=.2; schema="https://esia-portal1.test.gosuslugi.ru/rs/model/prn/Person-1"]

Пример раздела headers (разрывы строк даны для удобства чтения):

Содержательная часть ответа на запрос содержится в разделе body. Пример возвращаемых данных (разрывы строк даны для удобства чтения) о физическом лице:

Каждое описание объекта или коллекции содержит параметр stateFacts, указывающий на некоторые факты о предоставляемых сведениях. Возможны следующие значения stateFacts:

- Identifiable - имеет идентификатор (например, это конкретный контакт или документ);

- hasSize - имеет размер (например, для коллекции указывает на число элементов коллекции);

- FirstPage - первая страница списка;

- LastPage - последняя страница списка;

- Paginated - постраничный список;

- EntityRoot - корневой объект;

- ReadOnly - объект только для чтения.

Параметр stateFacts позволяет, в частности, производить разделение выводимых результатов по страницам. Следующий ответ представляет собой первую страницу некоторого перечня (фрагмент, разрывы строки даны для удобства чтения):

Из данного ответа видно, что на каждой странице отображается по 2 элемента.

Для ряда операций поддерживается возможность встраивания (embedding) связанных данных. Для этого в запросе соответствующего ресурса необходимо указывать параметр "embed", а в качестве его значения - сущность, которую требуется включить в ответ запроса. Например, при запросе следующего ресурса будут отображаться ссылки на контакты пользователя 100000:

Однако указание параметра "embed" позволяет получить данные о контактах непосредственно в ответе на следующий запрос:

В этом случае запрос данного ресурса будет возвращать ответ (фрагмент, разрывы строки даны для удобства чтения):

В данном случае на месте ссылок на связанные элементы встраиваются данные контактов.

При встраивании сохраняется возможность получать схемы возвращаемых ресурсов, например:

В этом случае данные об элементах будут возвращаться согласно первой схеме.

Также возможно встраивание нескольких ресурсов в запросе, например:

В этом случае в ответе вместо ссылок на сотрудников организации будут передаваться персональные данные сотрудников организации: ФИО, отчество, дата и место рождения, пол и т.д. Набор данных зависит от информации, указанной в профиле сотрудника.

При встраивании нескольких ресурсов также возможно указание на версии, например:

Перечень ссылок, которые могут быть встроены:

- данные о физических лицах:

- - контактные данные (contacts);

- - адреса (addresses);

- - документы (documents);

- - транспортные средства (vehicles);

- - организации, к которым принадлежит физическое лицо (organizations);

- данные об организациях:

- - контактные данные (contacts);

- - адреса (addresses);

- - транспортные средства (vehicles);

- данные о сотрудниках организации:

- - данные о сотруднике как физическом лице (person).

- данные по ссылкам, отображаемым в содержании ответа в разделе "elements" (возможность встраивания elements есть везде, где параметр stateFacts имеет значение "hasSize").

Далее приведены описания следующих операций программного интерфейса ЕСИА:

- предоставление персональных данных пользователей;

- проверка факта удаления учетной записи пользователя ЕСИА;

- предоставление сведений о вхождении пользователя в группы и организации;

- предоставление данных из профиля организации;

- предоставление списка участников группы или организации;

- предоставление сведений о вхождении пользователей в группы;

- управление данными организации;

- предоставление сведений о субъекте.