Unified Identity Management logo figure Unified Identity Management logo figure
Поиск Поиск по документации
day
mode night
mode
Скачать PDF

API управления привязками к социальным сетям

API предназначено для управления существующими привязками с соцсетями и внешними поставщиками учетных записей.

Авторизация

Авторизация запросов в Federation WebAPI работает через HTTP заголовок Authorization в формате "Bearer <oauth_token>"

  • <oauth_token> - OAuth 2.0 токен полученый от RooX RooX UIDM

Пример взаимодействия

Пример запроса и ответа

Запрос:

GET /webapi-1.0/customers/@me/partnerMappings HTTP/1.1 (1)
Authorization: Bearer AQIC5wM2LY... (2)
Host: {{sso_host}} (3)
Accept:*/* (4)

Ответ:

HTTP/1.1 200 OK (5)
Date: Thu, 29 May 2014 09:19:06 GMT (6)
Connection: close (7)
Cache-Control: no-cache (8)
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Pragma: no-cache
Content-Type: application/json;charset=UTF-8 (9)
Content-Length: 276 (10)
X-API-Maturity: stable (11)
X-Context-Id: QMUBJXIJIMP4SM (12)
X-Node-Id: ocb.hosted (13)
(14)
{
    "id": "1000000000",
    "balance": "300.45",
    "balanceDecimal": 300.45,
    "birthday": "2014-05-29T13:36:46.829+04:00",
    "lastName": "Иванов",
    "firstName": "Иван",
    "displayName": "Иванов Иван Иванович",
    "msisdn": "1000000000",
}

  1. Строка запроса, в примере запрашивается информация о привязках текущего пользователя (метод /customers/@me/partnerMappings). Пользователь определяется по авторизационному токену.

  2. Авторизационный токен

  3. Имя хоста с WebAPI

  4. Принимать любой тип данных. Можно указать application/json

  5. Строка статуса ответа. Указан код 200 OK, что означачает "запрос выполнен, ответ находится в теле ответа"

  6. Текущее время сервера

  7. Требования закрыть соединение. WebAPI всегда требует закрывать соединение

  8. Заголовки, запрещающие кеширование (WebAPI указывает сразу несколько для совместимости со всеми браузерами)

  9. Тип содержимого ответа, всегда application/json, кодировка UTF-8

  10. Длина тела ответа

  11. Заголовок, указывающий на стабильность интерфейса вызванного метода: stable (стабильный), experimental (новый API, может изменяться), deprecated (метод вскоре может быть удален). Для production всегда должно быть stable Если клиент встречает experimental или deprecated, он должен запротоколировать событие с уровнем WARNING

  12. Уникальный идентификатор запроса. Назначается сервером, используется для отладки и поиска сообщений в логах

  13. Идентификатор узла в кластере, который обработал запрос. Используется для отладки

  14. Тело ответа, в данном случае сущность Customer сериализованная в JSON

Базовые ошибки

Следующие ошибки не относятся к бизнес-логике некоторого метода, их может возвращать любой метод API.

401

Пользователь не аутентифицирован

403

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

404

Запрашиваемый объект не существует

429

Превышено число допустимых запросов к API

500

Общая ошибка сервера

400

Запрос синтаксически некорректен, не переданы обязательные параметры либо произошла любая другая ошибка. В данном случае пояснение причины находится в теле ответа в JSON-структуре error. См. пример 2.
Пример ответа 400 с расширенным кодом ошибки

Запрос:

GET /webapi-1.0/customers/@me/partnerMappings HTTP/1.1 (1)
Authorization: Bearer AQIC5wM2LY... (2)
Host: {{sso_host}}
Accept:*/*

Ответ:

HTTP/1.1 400 Bad Request (2)
X-Node-Id: ocb.hosted
X-Context-Id: UGJDB1ARYMGQ6I
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Pragma: no-cache
X-API-Maturity: stable
Content-Type: application/json;charset=UTF-8
Date: Thu, 29 May 2014 09:40:43 GMT
Connection: close
(3)
{
  "error": { (4)
    "code": -1001, (5)
    "message": "JMS", (6)
    "data": "javax.xml.ws.soap.SOAPFaultException: Could not send Message" (7)
  }
}

  1. Строка запроса, в примере запрашивается список привязок пользователя к социальным сетям

  2. Строка статуса ответа. Указан код 400 OK, что означачает "запрос не выполнен, пояснение находится в теле ответа в объекте error"

  3. Тело ответа, в данном случае информация об ошибке

  4. Контейнер информации об ошибке

  5. Расширенный код ошибки, в данном случае "отказ на стороне сторонней системы"

  6. Краткая информация об ошибке, в данном случае имя системы, в котором произошел отказ - JMS (это пример)

  7. Расширенная информация об ошибке, требуемая для анализа причины службой поддержки

Предполагается, что клиент не производит анализа дополнительного кода и трактует все 400-тые ответы, как общую ошибку WebAPI. Содержимое error необходимо передавать при обращении в службу техподдержки.

Методы API

Получение списка привязок текущего пользователя к профилям в социальных сетях

URL

/customers/:customerId/partnerMappings

Метод

GET

Назначение

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

URL-параметры

customerId - идентификатор. Допустимое значение @mе - специальный литерал для обозначения "текущего пользователя"

Тело запроса

нет

Возвращаемое значение

Список привязок
Пример запроса

Запрос:

GET /webapi-1.0/api/customer/@me/partnerMappings HTTP/1.1 (1)
Authorization: Bearer AQIC5wM2LY...
... (2)

Ответ:

HTTP/1.1 200 OK
(3)
[
  {
    "id": 839672,(4)
    "type": "social",
    "customerId": "9165711402",(5)
    "partnerId": "vkontakte",(6)
    "externalUser": {(7)
      "userId": "165842756",(8)
      "firstName": "Гарри",(9)
      "lastName": "Катфиш",(10)
      "middleName": "",(11)
      "fullName": "Гарри Катфиш",(12)
      "avatarUrl": "http://cs317630.vk.me/v317630756/694b/8e-nssu1vuA.jpg",(13)
      "avatarSmallUrl": "http://cs317630.vk.me/v317630756/694b/8e-nssu1vuA-small.jpg"(14)
    }
    "created": "2016-02-12T20:55:51+04:00"(15)
  },
  {
    "id": 834665,
    "type": "social",
    "customerId": "9165711402",
    "partnerId": "vkontakte",
    "externalUser": {
      "userId": "100003307166182",
      "firstName": "GarryTest",
      "lastName": "CatfishTest",
      "fullName": "GarryTest CatfishTest",
      "avatarUrl": "https://vk.ru/hprofile-xaf1/v/t1.0-1/s100x100/399254_291635237623379_1854864570_n.jpg?oh=c3d5788cc69b027a0e7a9361bb285e9c&oe=57429399",
    }
    "created": "2016-02-03T20:53:50+04:00"
  }
]

  1. Строка запроса

  2. В этом примере и далее несущественные заголовки ответа и запроса не указаны для сокращения места

  3. Тело ответа, в данном случае список сущностей PartnerMapping

  4. Уникальный идентификатор привязки. Используется, например, для удаления

  5. Идентификатор пользователя в RooX UIDM

  6. Идентификатор системы, в которой создана привязка. Для соцсетей содержит краткое имя соцсети

  7. Блок информации о пользователе на "стороне" соцсети. Информация целиком получена из API соцсети в момент создания привязки, некоторые поля могут отсутствовать, если пользователь их не заполнил либо сделал приватными

  8. Идентификатор пользователя в соцсети

  9. Имя пользователя в соцсети

  10. Фамилия пользователя в соцсети

  11. Отчество пользователя в соцсети

  12. Полное имя пользователя в соцсети (как правило ФИО)

  13. Ссылка на аватар пользователя

  14. Ссылка на уменьшенную копию аватара пользователя

  15. Дата и время создания привязки в формате ISO full date time

Удаление привязки текущего пользователя по идентификатору привязки

URL

GET /webapi-1.0/partnerMappings/:id HTTP/1.1 <1>

Метод

DELETE

Назначение

Удаление привязки по идентификатору привязки

URL-параметры

id - идентификатор привязки

GET-параметры

нет

Тело запроса

нет

Возвращаемое значение

Нет или ошибка

Идентификатор привязки следует получать используя метод получения списка привязок текущего пользователя

Пример

Запрос:

DELETE /webapi-1.3/socialUserMapping/1112211 HTTP/1.1(1)
Authorization: Bearer AQIC5wM2LY...
... (2)

Ответ:

HTTP/1.1 200 OK(3)

  1. Строка запроса

  2. В этом примере и далее несущественные заголовки ответа и запроса не указаны для сокращения места

  3. Код ответа, в данном случае 200 OK - запрос выполнен успешно

Объектная модель

Привязка пользователя к социальной сети (PartnerMapping)

Атрибут

Значение

Тип

Пример значения

id

Уникальный идентификатор привязки. Используется, например, для удаления

string

839672

type

Тип привязки. Всегда содержит social

string

social

customerId

Идентификатор пользователя в RooX UIDM

string

9165711402

partnerId

Идентификатор системы, в которой создана привязка. Для соцсетей содержит краткое имя соцсети

string

vkontakte

externalUser

Блок информации о пользователе на "стороне" соцсети.

object

created

Дата и время создания привязки

date в формате ISO full date time

2016-02-12T20:55:51+04:00
Таблица 1. Справочник соцсетей

vkontakte

Вконтакте

liveid

Microsoft LiveID

Профиль пользователя в социальной сети (ExternalUser)

Атрибут

Значение

Тип

Пример значения

userId

Идентификатор пользователя в соцсети

string

165842756

firstName

Имя пользователя в соцсети

string

Гарри

lastName

Фамилия пользователя в соцсети

string

Катфиш

middleName

Отчество пользователя в соцсети

string

fullName

Полное имя пользователя в соцсети

string

ГарриКатфиш

avatarUrl

Ссылка на аватар пользователя

string

http://cs317630.vk.me/v317630756/694b/8e-nssu1vuA.jpg