Дакументацыя сервернага API Loomio

/api/server0 прызначаны для аперацый на ўзроўні сервера. Выкарыстоўвайце /api/user0 для дзеянняў ад імя ўліковага запісу Loomio.

Выкарыстоўвайце адзін серверны ключ для стварэння ўліковых запісаў і кіравання імі, пошуку груп ва ўсёй інсталяцыі і кіравання ўдзелам у гэтых групах і ролямі. Уліковы запіс бота, карыстальніцкі ключ API або ўдзел у групах не патрабуюцца. Карыстальніцкія ключы API па-ранейшаму падпарадкоўваюцца дазволам адпаведных уліковых запісаў у групах.

Аўтэнтыфікацыя

Ключ задаецца наладай SERVER_API_KEY у асяроддзі сервера. Для новых інсталяцый яго генеруе create_env.sh.

Перадавайце ключ як токен Bearer:

curl -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users

Перадавайце даныя для аўтэнтыфікацыі толькі ў загалоўку Authorization. Ключы API ў радках запыту або целах запытаў адхіляюцца.

Стварэнне ўліковых запісаў і кіраванне ўдзелам у групах

Метад	Канцавы пункт	Прызначэнне
`POST`	`/api/server0/users`	Стварыць уліковы запіс
`GET`	`/api/server0/groups`	Знайсці групы ва ўсёй інсталяцыі
`GET`	`/api/server0/memberships`	Атрымаць спіс запісаў аб удзеле ў групе
`POST`	`/api/server0/memberships`	Запрасіць удзельнікаў або сінхранізаваць поўны спіс удзельнікаў
`PATCH`	`/api/server0/memberships/:id`	Змяніць ролі адміністратараў групы і дэлегатаў
`DELETE`	`/api/server0/memberships/:id`	Скасаваць адзін запіс аб удзеле ў групе

Канцавыя пункты для абнаўлення, дэактывацыі, паўторнай актывацыі, абязлічвання і выдалення наяўных уліковых запісаў апісаны ніжэй.

Стварэнне ўліковага запісу

POST /api/server0/users

Адпраўце аб’ект user з абавязковым полем email. Прабелы па краях адрасоў электроннай пошты выдаляюцца, а літары пераводзяцца ў ніжні рэгістр. Неабавязковыя палі: name, username і is_admin. Тут is_admin азначае ролю адміністратара інсталяцыі; ролі адміністратараў групы задаюцца ў запісах аб удзеле ў групе. Не ўказвайце username, каб згенераваць яго аўтаматычна. Невядомыя палі адхіляюцца.

curl https://loomio.example.org/api/server0/users \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY' \
  --json '{
    "user": {
      "email": "ada@example.org",
      "name": "Ada Lovelace",
      "username": "ada",
      "is_admin": false
    }
  }'

Адказ мае код HTTP 201 і змяшчае аб’ект user. Пры некарэктных палях або адрасе электроннай пошты ці імені карыстальніка, якія ўжо выкарыстоўваюцца, вяртаецца HTTP 422. Стварэнне ўліковага запісу не адпраўляе запрашэнне, не выконвае ўваход і не пазначае адрас электроннай пошты як пацверджаны. Запрасіце людзей у групу праз канцавы пункт для кіравання ўдзелам у групах, каб адправіць запрашэнне праз звычайны механізм апавяшчэнняў.

Пошук груп

GET /api/server0/groups

Атрымайце спіс усіх груп, якія не былі выдалены, у тым ліку прыватных груп і груп з пратэрмінаванымі падпіскамі. Вынікі ўпарадкаваны паводле ўзрастання ID. Выкарыстоўвайце limit (значэнне па змаўчанні і максімум — 50) і offset (па змаўчанні — 0) для пастаронкавага прагляду.

curl 'https://loomio.example.org/api/server0/groups?limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY'

{
  "groups": [
    {
      "id": 123,
      "key": "examplegroup",
      "name": "Planning group",
      "handle": "planning",
      "parent_id": null,
      "group_privacy": "secret"
    }
  ],
  "meta": {
    "total": 1
  }
}

Спіс запісаў аб удзеле ў групе

GET /api/server0/memberships?group_id=123

Параметр group_id абавязковы. Вынікі ўключаюць запісы аб пацверджаным удзеле ў групе і запрашэнні, якія чакаюць прыняцця, упарадкаваныя паводле ўзрастання ID запісу аб удзеле. Скасаваныя запісы аб удзеле выключаюцца. Выкарыстоўвайце limit (значэнне па змаўчанні і максімум — 50) і offset (па змаўчанні — 0) для пастаронкавага прагляду.

curl 'https://loomio.example.org/api/server0/memberships?group_id=123&limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY'

{
  "memberships": [
    {
      "id": 456,
      "group_id": 123,
      "user_id": 789,
      "user_email": "ada@example.org",
      "user_name": "Ada Lovelace",
      "admin": false,
      "delegate": false,
      "accepted_at": null,
      "pending": true
    }
  ],
  "meta": {
    "total": 1
  }
}

admin і delegate — гэта ролі ў групе. accepted_at змяшчае дату і час прыняцця запрашэння або null, пакуль запрашэнне чакае прыняцця. Гэты канцавы пункт не раскрывае токены запрашэнняў, даныя для ўваходу або галасы.

Запрашэнне або сінхранізацыя ўдзельнікаў

POST /api/server0/memberships

Адпраўце абавязковыя group_id і масіў emails. Па змаўчанні гэта дадае людзей са спіса, якія яшчэ не маюць актыўнага ўдзелу ў групе, і захоўвае ўдзел усіх астатніх. Прабелы па краях адрасоў электроннай пошты выдаляюцца, літары пераводзяцца ў ніжні рэгістр, а дублікаты выдаляюцца. Для новых адрасоў ствараюцца ўліковыя запісы і запрашэнні, якія чакаюць прыняцця. Наяўныя ўдзельнікі іншай актыўнай групы ў той жа арганізацыі з пацверджанымі адрасамі электроннай пошты прымаюцца аўтаматычна, як і пры запрашэнні праз карыстальніцкі API.

curl https://loomio.example.org/api/server0/memberships \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY' \
  --json '{
    "group_id": 123,
    "emails": [
      "ada@example.org",
      "alex@example.org"
    ]
  }'

Каб сінхранізаваць поўны спіс удзельнікаў, яўна задайце для remove_absent значэнне true. Усе, каго няма ў спісе, выдаляюцца з гэтай групы і яе падгруп. Пусты масіў з remove_absent: true выдаляе ўсіх, у тым ліку адміністратараў групы. Не ўказвайце remove_absent або задайце для яго false, калі толькі дадаяце людзей. Таксама прымаюцца састарэлыя значэнні 1 і 0.

curl https://loomio.example.org/api/server0/memberships \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY' \
  --json '{
    "group_id": 123,
    "emails": [
      "ada@example.org"
    ],
    "remove_absent": true
  }'

{
  "added_emails": [],
  "removed_emails": [
    "alex@example.org"
  ]
}

Паўтарэнне таго ж запыту не стварае дублікатаў запісаў аб удзеле і не адпраўляе запрашэнні паўторна. Паўторнае запрашэнне людзей са скасаваным удзелам аднаўляе іх доступ да групы, але не аднаўляе ранейшую ролю адміністратара. Новыя запрашэнні і змены роляў выкарыстоўваюць звычайны механізм апавяшчэнняў; пры гэтым ніводны ўліковы запіс не пазначаецца як ініцыятар дзеяння.

Пры адсутнасці спіса адрасоў электроннай пошты, яго некарэктным фармаце або недапушчальных лагічных значэннях вяртаецца HTTP 400. Калі ў спісе ёсць дэактываваны ўліковы запіс, вяртаецца HTTP 422; перад даданнем яўна актывуйце яго паўторна. Некарэктныя даныя ўліковых запісаў, абмежаванні падпіскі або іншыя памылкі адмяняюць усю сінхранізацыю, у тым ліку стварэнне новых уліковых запісаў і выдаленне ўдзельнікаў з групы. Дадаванне патрабуе актыўнай групы і падпарадкоўваецца абмежаванням падпіскі на колькасць удзельнікаў.

Абнаўленне роляў удзельнікаў

PATCH /api/server0/memberships/:id

Адпраўце аб’ект membership з адным або абодвума лагічнымі палямі admin і delegate. Ролі, якія не ўказаны, застаюцца без змен. Невядомыя палі адхіляюцца; гэты канцавы пункт не дазваляе перанесці запіс аб удзеле, прыняць запрашэнне або змяніць вагу галасоў.

curl https://loomio.example.org/api/server0/memberships/456 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY' \
  --json '{
    "membership": {
      "admin": true,
      "delegate": false
    }
  }'

Вяртаецца аб’ект membership з тымі ж палямі, што і ў запісе аб удзеле са спіса. Прызначэнне ролі стварае звычайнае апавяшчэнне аб ролі; паўторнае задаванне нязмененай ролі не адпраўляе апавяшчэнне паўторна. Для змены роляў патрабуецца актыўная група. Для скасаваных запісаў аб удзеле вяртаецца HTTP 404.

Скасаванне аднаго запісу аб удзеле

DELETE /api/server0/memberships/:id

curl https://loomio.example.org/api/server0/memberships/456 \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY'

Вяртаецца {"success": true}. Выдаленне скасоўвае доступ да групы і яе падгруп, у тым ліку доступ да тэм і права галасаваць у актыўных апытаннях. Яно не выдаляе ўліковы запіс, не змяняе іншыя групы і не скасоўвае непасрэдна прадастаўлены доступ да тэм. Паўторнае выдаленне завяршаецца паспяхова. Вы можаце скасоўваць удзел у групах з пратэрмінаванымі падпіскамі; для выдаленых груп вяртаецца HTTP 404.

Аб’ект уліковага запісу

Адказы з данымі ўліковых запісаў маюць такую структуру:

{
  "id": 123,
  "name": "Ada Lovelace",
  "username": "ada",
  "email": "ada@example.org",
  "is_admin": false,
  "active": true,
  "deactivated_at": null,
  "identities": [
    {
      "id": 456,
      "identity_type": "oauth",
      "uid": "external-123",
      "email": "ada@example.org",
      "name": "Ada Lovelace"
    }
  ]
}

Спіс уліковых запісаў

Атрымайце спіс усіх уліковых запісаў у інсталяцыі Loomio.

GET /api/server0/users

Прыклад

curl -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users

Вяртае:

{
  "users": []
}

Прагляд уліковага запісу

Знайдзіце ўліковы запіс паводле ID у Loomio або знешняй ідэнтычнасці.

GET /api/server0/users/:id

GET /api/server0/users/identity/:identity_type/:uid

Прыклады

Паводле ID уліковага запісу ў Loomio:

curl -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/123

Паводле знешняй ідэнтычнасці:

curl -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/identity/oauth/external-123

Вяртае:

{
  "user": {}
}

Абнаўленне ўліковага запісу

Абнавіце палі профілю ўліковага запісу, знойдзенага паводле ID у Loomio або знешняй ідэнтычнасці.

PATCH /api/server0/users/:id

PATCH /api/server0/users/identity/:identity_type/:uid

Параметры

Поле	Апісанне
`name`	Імя для адлюстравання
`username`	Імя карыстальніка ў Loomio
`email`	Адрас электроннай пошты

Прыклады

Паводле ID уліковага запісу ў Loomio:

curl -X PATCH \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"user":{"name":"Ada Lovelace","username":"ada","email":"ada@example.org"}}' \
  https://www.loomio.com/api/server0/users/123

Паводле знешняй ідэнтычнасці:

curl -X PATCH \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"user":{"name":"Ada Lovelace","username":"ada","email":"ada@example.org"}}' \
  https://www.loomio.com/api/server0/users/identity/oauth/external-123

Вяртае абноўлены ўліковы запіс:

{
  "user": {}
}

Дэактывацыя ўліковага запісу

Дэактывуйце ўліковы запіс, знойдзены паводле ID у Loomio або знешняй ідэнтычнасці.

POST /api/server0/users/:id/deactivate

POST /api/server0/users/identity/:identity_type/:uid/deactivate

Прыклады

Паводле ID уліковага запісу ў Loomio:

curl -X POST -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/123/deactivate

Паводле знешняй ідэнтычнасці:

curl -X POST -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/identity/oauth/external-123/deactivate

Вяртае:

{
  "success": true,
  "user": {}
}

Паўторная актывацыя ўліковага запісу

Паўторна актывуйце дэактываваны ўліковы запіс, знойдзены паводле ідэнтыфікатара ў Loomio або знешняй ідэнтычнасці.

POST /api/server0/users/:id/reactivate

POST /api/server0/users/identity/:identity_type/:uid/reactivate

Прыклады

Паводле ідэнтыфікатара ў Loomio:

curl -X POST -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/123/reactivate

Паводле знешняй ідэнтычнасці:

curl -X POST -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/identity/oauth/external-123/reactivate

Вяртае:

{
  "success": true,
  "user": {}
}

Выдаленне асабістых даных

Выдаленне асабістых даных захоўвае каментарыі і іншы створаны карыстальнікамі кантэнт у іх групах, але выдаляе вядомыя звесткі, якія дазваляюць ідэнтыфікаваць асобу: імя, біяграфію, фота профілю, адрас электроннай пошты, уліковыя даныя для ўваходу, ідэнтычнасці і актыўныя сеансы.

Гэта рэкамендаваны спосаб выдалення ўліковага запісу з Loomio.

POST /api/server0/users/:id/redact

POST /api/server0/users/identity/:identity_type/:uid/redact

Прыклады

Паводле ідэнтыфікатара ў Loomio:

curl -X POST -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/123/redact

Паводле знешняй ідэнтычнасці:

curl -X POST -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/identity/oauth/external-123/redact

Вяртае:

{
  "success": true
}

Выдаленне ўліковага запісу

Выдаленне прыбірае ўліковы запіс і створаныя праз яго запісы. Каментарыі выдаляюцца з тэм, галасы — з апытанняў, а групы, абмеркаванні, апытанні і іншыя запісы, створаныя праз гэты ўліковы запіс, таксама могуць быць выдаленыя праз сувязі ў базе даных.

Гэта прыводзіць да значнай страты даных. Настойліва рэкамендуецца замест гэтага выдаліць асабістыя даныя.

DELETE /api/server0/users/:id

DELETE /api/server0/users/identity/:identity_type/:uid

Прыклады

Паводле ідэнтыфікатара ў Loomio:

curl -X DELETE -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/123

Паводле знешняй ідэнтычнасці:

curl -X DELETE -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/identity/oauth/external-123

Вяртае:

{
  "success": true
}

Налады сінхранізацыі профілю праз SSO

Выкарыстоўвайце гэтыя налады, калі палямі профілю Loomio кіруе іншая сістэма.

LOOMIO_DISABLE_EDIT_USER_PROFILE=1
# LOOMIO_SSO_UPDATE_USER_PROFILE_ON_LOGIN=1

LOOMIO_DISABLE_EDIT_USER_PROFILE=1 забараняе карыстальнікам самастойна рэдагаваць гэтыя палі:

Поле	Заўвагі
`name`	Кіруецца знешняй сінхранізацыяй
`username`	Кіруецца знешняй сінхранізацыяй
`email`	Кіруецца знешняй сінхранізацыяй
`avatar_kind` / `uploaded_avatar`	Кіруецца знешняй сінхранізацыяй

Карыстальнікі па-ранейшаму могуць рэдагаваць лакальныя палі Loomio, напрыклад short_bio і location.

LOOMIO_SSO_UPDATE_USER_PROFILE_ON_LOGIN=1 абнаўляе name і email з даных уваходу праз SSO. Пакіньце гэту зменную закаментаванай або не задавайце яе, калі знешні скрыпт сінхранізацыі павінен быць адзінай крыніцай гэтых абнаўленняў.

LOOMIO_SSO_FORCE_USER_ATTRS па-ранейшаму працуе ў існых усталёўках. Гэта зменная адначасова забараняе карыстальнікам рэдагаваць палі і абнаўляе name і email пры ўваходзе праз SSO.

Гэтая старонка перакладзена аўтаматычна. Калі слова няправільнае або незразумелае, напішыце на contact@loomio.org, і мы выправім яго.