Loomion palvelimen API:n dokumentaatio

/api/server0 on tarkoitettu palvelintason toimintoihin. Käytä /api/user0-rajapintaa käyttäjäkohtaisiin toimintoihin, jotka suoritetaan Loomion käyttäjätilillä.

Yhdellä palvelinavaimella voit luoda ja hallita tilejä, etsiä ryhmiä koko asennuksesta ja hallita niiden jäsenyyksiä ja rooleja. Bottitiliä, käyttäjän API-avainta tai ryhmien jäsenyyttä ei tarvita. Käyttäjien API-avaimet noudattavat edelleen käyttäjän ryhmäkohtaisia käyttöoikeuksia.

Todennus

Avain määritetään palvelinympäristön SERVER_API_KEY-asetuksella. create_env.sh luo avaimen uusille asennuksille.

Lähetä avain bearer-tokenina:

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

Lähetä tunnistetiedot vain Authorization-otsakkeessa. Kyselymerkkijonoissa tai pyyntöjen rungoissa lähetetyt API-avaimet hylätään.

Tilien ja jäsenyyksien luominen ja hallinta

Olemassa olevien tilien päivittämisen, käytöstä poistamisen, uudelleenaktivoinnin, henkilötietojen poistamisen ja tilien poistamisen päätepisteet kuvataan alempana.

Luo tili

POST /api/server0/users

Lähetä user-objekti, joka sisältää pakollisen email-kentän. Sähköpostiosoitteiden alusta ja lopusta poistetaan tyhjämerkit, ja osoitteet muunnetaan pieniksi kirjaimiksi. Valinnaiset kentät ovat name, username ja is_admin. Tässä is_admin tarkoittaa koko asennuksen ylläpitäjää; ryhmän ylläpitäjärooleja hallitaan jäsenyyksien kautta. Jätä username pois, jos haluat luoda käyttäjänimen automaattisesti. Tuntemattomat kentät hylätään.

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
    }
  }'

Vastauksena palautetaan HTTP 201 ja user-objekti. Virheelliset kentät tai jo käytössä oleva sähköpostiosoite tai käyttäjänimi palauttavat HTTP 422. Tilin luominen ei lähetä kutsua, kirjaa henkilöä sisään eikä merkitse hänen sähköpostiosoitettaan vahvistetuksi. Kutsu hänet ryhmään jäsenyyksien päätepisteen kautta, jolloin kutsu lähetetään tavallisen ilmoitusprosessin mukaisesti.

Etsi ryhmiä

GET /api/server0/groups

Listaa kaikki ryhmät, joita ei ole poistettu, mukaan lukien yksityiset ryhmät ja ryhmät, joiden tilaus on päättynyt. Tulokset järjestetään tunnuksen mukaan nousevaan järjestykseen. Selaa tuloksia sivuittain parametreilla limit (oletus ja enimmäisarvo 50) ja offset (oletus 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
  }
}

Listaa jäsenyydet

GET /api/server0/memberships?group_id=123

group_id on pakollinen. Tulokset sisältävät hyväksytyt jäsenyydet ja odottavat kutsut jäsenyyden tunnuksen mukaan nousevassa järjestyksessä. Perutut jäsenyydet jätetään pois. Käytä sivutukseen parametreja limit (oletus ja enimmäisarvo 50) ja offset (oletus 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 ja delegate ovat ryhmän rooleja. accepted_at on hyväksymisen aikaleima tai null, kun kutsu odottaa hyväksymistä. Tämä päätepiste ei paljasta kutsutunnisteita, kirjautumistietoja eikä ääniä.

Kutsu tai synkronoi jäseniä

POST /api/server0/memberships

Lähetä pakolliset group_id ja emails-taulukko. Oletusarvoisesti tämä lisää luettelon henkilöt, joilla ei vielä ole aktiivista jäsenyyttä, ja säilyttää muiden jäsenyydet ennallaan. Sähköpostiosoitteiden alusta ja lopusta poistetaan tyhjämerkit, osoitteet muunnetaan pieniksi kirjaimiksi ja kaksoiskappaleet poistetaan. Uusille osoitteille luodaan tilit ja odottavat kutsut. Saman organisaation toisen aktiivisen ryhmän olemassa olevat vahvistetut jäsenet hyväksytään automaattisesti käyttäjän API:n kutsuprosessin mukaisesti.

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"
    ]
  }'

Synkronoi koko jäsenluettelo asettamalla remove_absent nimenomaisesti arvoon true. Kaikki luettelosta puuttuvat poistetaan kyseisestä ryhmästä ja sen alaryhmistä. Tyhjä taulukko yhdessä asetuksen remove_absent: true kanssa poistaa kaikki, myös ryhmän ylläpitäjät. Jätä remove_absent pois tai aseta sen arvoksi false, kun vain lisäät henkilöitä. Myös vanhat arvot 1 ja 0 hyväksytään.

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"
  ]
}

Saman pyynnön toistaminen ei luo päällekkäisiä jäsenyyksiä eikä lähetä kutsuja uudelleen. Jäsenen, jonka jäsenyys on peruttu, kutsuminen uudelleen palauttaa hänen pääsynsä ryhmään mutta ei aiempaa ylläpitäjäroolia. Uudet kutsut ja roolimuutokset käyttävät tavallista ilmoitusprosessia, eikä ketään käyttäjää kirjata toiminnon tekijäksi.

Puuttuvat tai väärin muotoillut sähköpostiluettelot ja virheelliset totuusarvot palauttavat HTTP 400. Luettelossa oleva käytöstä poistettu tili palauttaa HTTP 422; aktivoi se erikseen uudelleen ennen lisäämistä. Virheelliset tilitiedot, tilauksen rajoitukset tai muut virheet peruuttavat koko synkronoinnin, mukaan lukien uudet tilit ja jäsenyyksien poistot. Lisääminen edellyttää aktiivista ryhmää, ja tilauksen jäsenmäärärajoitukset ovat voimassa.

Päivitä jäsenyyden roolit

PATCH /api/server0/memberships/:id

Lähetä membership-objekti, joka sisältää joko toisen tai molemmat totuusarvokentistä admin ja delegate. Pois jätetyt roolit säilyvät ennallaan. Tuntemattomat kentät hylätään; päätepisteellä ei voi siirtää jäsenyyttä, hyväksyä kutsua eikä muuttaa äänten painotuksia.

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

Palauttaa membership-objektin, jossa on samat kentät kuin listatussa jäsenyydessä. Roolin myöntäminen luo tavallisen rooli-ilmoituksen; muuttumattoman roolin lähettäminen uudelleen ei lähetä uutta ilmoitusta. Roolimuutokset edellyttävät aktiivista ryhmää. Perutut jäsenyydet palauttavat HTTP 404.

Poista yksittäinen jäsenyys

DELETE /api/server0/memberships/:id

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

Palauttaa {"success": true}. Poistaminen peruu pääsyn ryhmään ja sen alaryhmiin, mukaan lukien pääsyn aiheisiin ja äänioikeuden aktiivisissa kyselyissä. Se ei poista tiliä, muuta muita ryhmiä eikä poista suoraa pääsyä ketjuihin. Poistamisen toistaminen onnistuu. Voit poistaa jäsenyyksiä ryhmistä, joiden tilaus on päättynyt; poistetut ryhmät palauttavat HTTP 404.

Käyttäjäobjekti

Käyttäjätietoja sisältävien vastausten rakenne on seuraava:

{
  "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"
    }
  ]
}

Listaa käyttäjät

Listaa kaikki Loomio-asennuksen käyttäjätilit.

GET /api/server0/users

Esimerkki

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

Palauttaa:

{
  "users": []
}

Näytä käyttäjä

Etsi käyttäjä Loomion käyttäjä-ID:n tai ulkoisen identiteetin perusteella.

GET /api/server0/users/:id

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

Esimerkkejä

Loomion käyttäjä-ID:n perusteella:

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

Ulkoisen identiteetin perusteella:

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

Palauttaa:

{
  "user": {}
}

Päivitä käyttäjä

Päivitä Loomion käyttäjä-ID:n tai ulkoisen identiteetin perusteella löydetyn käyttäjän profiilikentät.

PATCH /api/server0/users/:id

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

Parametrit

Esimerkkejä

Loomion käyttäjä-ID:n perusteella:

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

Ulkoisen identiteetin perusteella:

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

Palauttaa päivitetyn käyttäjän:

{
  "user": {}
}

Poista käyttäjätili käytöstä

Poista käytöstä käyttäjätili, joka on löydetty Loomion käyttäjä-ID:n tai ulkoisen identiteetin perusteella.

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

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

Esimerkkejä

Loomion käyttäjä-ID:n perusteella:

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

Ulkoisen identiteetin perusteella:

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

Palauttaa:

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

Aktivoi käyttäjä uudelleen

Aktivoi käytöstä poistettu käyttäjätili uudelleen Loomion käyttäjätunnisteen tai ulkoisen identiteetin perusteella.

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

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

Esimerkkejä

Loomion käyttäjätunnisteen perusteella:

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

Ulkoisen identiteetin perusteella:

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

Palauttaa:

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

Poista käyttäjän tunnistetiedot

Tunnistetietojen poistaminen säilyttää käyttäjän kommentit ja muun käyttäjän luoman sisällön hänen ryhmissään, mutta poistaa tiedossa olevat henkilön tunnistamiseen käytettävät tiedot, kuten nimen, esittelyn, profiilikuvan, sähköpostiosoitteen, kirjautumistiedot, identiteetit ja aktiiviset istunnot.

Tämä on suositeltu tapa poistaa käyttäjä Loomiosta.

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

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

Esimerkkejä

Loomion käyttäjätunnisteen perusteella:

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

Ulkoisen identiteetin perusteella:

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

Palauttaa:

{
  "success": true
}

Poista käyttäjä

Poistaminen poistaa käyttäjän ja hänen luomansa tietueet. Kommentit poistetaan ketjuista ja äänet kyselyistä. Myös käyttäjän luomat ryhmät, keskustelut, kyselyt ja muut tietueet voivat poistua tietokannan tietueiden välisten suhteiden kautta.

Tämä poistaa laajasti tietoja. Käyttäjän tunnistetietojen poistaminen on vahvasti suositeltu vaihtoehto.

DELETE /api/server0/users/:id

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

Esimerkkejä

Loomion käyttäjätunnisteen perusteella:

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

Ulkoisen identiteetin perusteella:

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

Palauttaa:

{
  "success": true
}

SSO-profiilin synkronointiasetukset

Käytä näitä asetuksia, kun toinen järjestelmä hallinnoi Loomion profiilikenttiä.

LOOMIO_DISABLE_EDIT_USER_PROFILE=1
# LOOMIO_SSO_UPDATE_USER_PROFILE_ON_LOGIN=1

LOOMIO_DISABLE_EDIT_USER_PROFILE=1 estää käyttäjiä muokkaamasta itse seuraavia kenttiä:

Käyttäjät voivat edelleen muokata Loomion paikallisia kenttiä, kuten short_bio ja location.

LOOMIO_SSO_UPDATE_USER_PROFILE_ON_LOGIN=1 päivittää kentät name ja email SSO-kirjautumistiedoista. Jätä asetus kommentoiduksi tai määrittämättä, kun vain ulkoisen synkronointiskriptin on tarkoitus päivittää näitä kenttiä.

LOOMIO_SSO_FORCE_USER_ATTRS toimii edelleen olemassa olevissa asennuksissa. Se sekä estää käyttäjiä muokkaamasta kenttiä että päivittää kentät name ja email SSO-kirjautumisen yhteydessä.