תיעוד API השרת של Loomio

/api/b3 מיועד לפעולות ברמת השרת. לפעולות ברמת המשתמש המתבצעות באמצעות חשבון משתמש ב-Loomio, יש להשתמש ב-/api/b2.

אימות

יש להגדיר את B3_API_KEY לערך סודי שאורכו יותר מ-16 תווים.

יש לשלוח את המפתח כאסימון Bearer:

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

יש לשלוח פרטי אימות רק בכותרת Authorization. מפתחות API במחרוזות שאילתה או בגופי בקשות נדחים.

אובייקט משתמש

תגובות המכילות נתוני משתמש הן במבנה הבא:

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

רשימת משתמשים

ניתן לקבל רשימה של כל חשבונות המשתמשים בהתקנת Loomio.

GET /api/b3/users

דוגמה

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

התגובה:

{
  "users": []
}

הצגת משתמש

ניתן לאתר חשבון משתמש לפי מזהה המשתמש ב-Loomio או לפי זהות חיצונית.

GET /api/b3/users/:id

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

דוגמאות

לפי מזהה המשתמש ב-Loomio:

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

לפי זהות חיצונית:

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

התגובה:

{
  "user": {}
}

עדכון משתמש

ניתן לעדכן את שדות הפרופיל של חשבון משתמש שאותר לפי מזהה המשתמש ב-Loomio או לפי זהות חיצונית.

PATCH /api/b3/users/:id

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

פרמטרים

דוגמאות

לפי מזהה המשתמש ב-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/b3/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/b3/users/identity/oauth/external-123

התגובה מכילה את נתוני המשתמש המעודכנים:

{
  "user": {}
}

השבתת משתמש

ניתן להשבית חשבון משתמש שאותר לפי מזהה המשתמש ב-Loomio או לפי זהות חיצונית.

POST /api/b3/users/:id/deactivate

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

דוגמאות

לפי מזהה המשתמש ב-Loomio:

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

לפי זהות חיצונית:

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

התגובה:

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

הפעלה מחדש של חשבון

ניתן להפעיל מחדש חשבון מושבת באמצעות מזהה החשבון ב־Loomio או זהות חיצונית.

POST /api/b3/users/:id/reactivate

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

דוגמאות

לפי מזהה החשבון ב־Loomio:

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

לפי זהות חיצונית:

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

התשובה המוחזרת:

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

הסרת פרטים מזהים מחשבון

הסרת פרטים מזהים משאירה בקבוצות את התגובות ואת התוכן האחר שנוצר באמצעות החשבון, אך מסירה מידע אישי מזהה ידוע כגון שם, תיאור אישי, תמונת פרופיל, כתובת דוא״ל, פרטי התחברות, זהויות והפעלות פעילות.

זו הדרך המומלצת להסרת חשבון מ־Loomio.

POST /api/b3/users/:id/redact

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

דוגמאות

לפי מזהה החשבון ב־Loomio:

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

לפי זהות חיצונית:

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

התשובה המוחזרת:

{
  "success": true
}

מחיקת חשבון

מחיקה מסירה את החשבון ואת הרשומות שנוצרו באמצעותו. תגובות מוסרות משרשורים, הצבעות מוסרות מסקרים, וגם קבוצות, דיונים, סקרים ורשומות אחרות שנוצרו באמצעות החשבון עשויים להימחק עקב קשרים בין רשומות במסד הנתונים.

פעולה זו גורמת למחיקה נרחבת של נתונים. מומלץ מאוד להסיר פרטים מזהים במקום זאת.

DELETE /api/b3/users/:id

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

דוגמאות

לפי מזהה החשבון ב־Loomio:

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

לפי זהות חיצונית:

curl -X DELETE -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/b3/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 מונע עריכה עצמאית של השדות הבאים:

עדיין ניתן לערוך שדות מקומיים של Loomio כגון short_bio ו־location.

LOOMIO_SSO_UPDATE_USER_PROFILE_ON_LOGIN=1 מעדכן את name ואת email מתוך נתוני ההתחברות באמצעות SSO. יש להשאיר שורה זו כהערה או לא להגדיר את המשתנה כאשר סקריפט סנכרון חיצוני אמור להיות המקור היחיד לעדכונים אלה.

LOOMIO_SSO_FORCE_USER_ATTRS ממשיך לפעול בהתקנות קיימות. הוא גם מונע עריכה עצמאית וגם מעדכן את name ואת email בעת התחברות באמצעות SSO.