Graphene Group Sync

While it is possible to manage groups and group memberships entirely within Graphene (by way of the Admin Interface), it is likely that some Graphene installations may want to take advantage of an automated "group sync" process. Graphene exposes a number of RESTful APIs to make this possible.

• A Reference Implementation of the Graphene Group Sync in PHP is available here

Table of Contents
Video Tutorial
Setting Up API Access Permissions
Getting Members Of A Group
Adding Members To A Group
Deleting Members From A Group

Video Tutorial

Setting Up API Access Permissions

All APIs for managing and enabling Graphene Group Sync capability require that an "API Account" be set up within the Graphene Interface. To create an API Account, log into graphene (as a site admin), visit the Admin panel, and click on API Accounts from the sidebar. From here, you should be able to create, update, and delete API Accounts.

Note: be careful with these API Accounts, as they enable full and unlimited access to any/all of Graphene's publicly exposed APIs

Once set up, the Group Sync APIs require basic HTTP authentication.

Using the curl command line tool, a basic API call might look like this (where USERNAME and PASSWORD are the API Account App Name / App Secret specified previously:

curl \
  -X GET \
  -u USERNAME:PASSWORD \
  https://graphene.example.com/api/public/groups/members/AMAZGROUP

Managing Group Memberships

Use of these APIs assumes that the groups already exist, and have a uniquely defined "slug". You can use these 3 APIs to fetch the existing members of a group, add new members to a group, and remove existing members from the group.

GET /api/public/groups/members/{slug}?status={external|internal}

Returns an array of users who are a member of group with the specified "slug"

Parameters

Parameter	Param Type	Required	Description
slug	"PATH" variable	true	This is the unique name/slug of the group
status	"GET" variable	false	external (list of members which were added via the API), or internal (list of users who were added via the admin interface)

Example Inputs:

Path

GET /api/public/groups/members/AMAZGROUP

Example Output:

[
  {
    "unique_id":"12345",
    "first_name":"Jane",
    "last_name":"Doe",
    "email":"jdoe@example.com",
    "params":{
      "favorite_pizza":"pepperoni"
    }
  },
  {
    "unique_id":"67890",
    "first_name":"John",
    "last_name":"Doe",
    "email":"jdoe2@example.com",
    "params":{
      "favorite_pizza":"cheese"
    }
  }
]

Response Codes

Code	Meaning
200	Success
404	Group Not Found
400	Malformed Request (slug missing?)
500	Error Processing Request

POST /api/public/groups/members/{slug}

Accepts an array of users and adds them to the group specified by the group "slug".

Behavior:

Users match on either the "unique_id" or "email_address" fields.

If a given user exists, their user record will be updated with the new information (first_name, last_name, etc) and their additional user parameters will be merged with the existing record.

If a given user cannot be found, the user will be created.

Parameters

Parameter	Param Type	Required	Description
slug	"PATH" variable	true	This is the unique name/slug of the group
members	x-www-form-urlencoded	true	x-www-form-urlencoded encoded array of users

Example Inputs:

Path

POST /api/public/groups/members/AMAZGROUP

x-www-form-urlencoded payload

members[0][unique_id]=12345&members[0][first_name]=Jane&members[0][last_name]=Doe&members[0][email]=jdoe@example.com&members[0][params][favorite_pizza]=pepperoni&members[1][unique_id]=67890&members[1][first_name]=John&members[1][last_name]=Doe&members[1][email]=jdoe2@example.com&members[1][params][favorite_pizza]=cheese

Example Output:

{
  "id":5,
  "site_id":1,
  "name":"Amazing Group",
  "slug":"AMAZGROUP",
  "unlisted":0,
  "order":1,
  "created_at":"2020-01-01 00:00:00",
  "updated_at":"2020-01-02 00:00:00",
}

Response Codes

Code	Meaning
200	Success (All Users Added to Group)
404	Group Not Found
400	Malformed Request (slug missing?)
500	Error Processing Request

DELETE /api/public/groups/members/{slug}

Accepts an array of users and removes them from the group specified by the group "slug".

Behavior:

Users match on the "unique_id" field.

If a given user exists, they are removed from the specified group.

Note: The user is not updated, modified, or changed in any way. Only their affiliation with the group is changed

Parameters

Parameter	Param Type	Required	Description
slug	"PATH" variable	true	This is the unique name/slug of the group
members	x-www-form-urlencoded	true	x-www-form-urlencoded encoded array of users

Example Inputs:

Path

DELETE /api/public/groups/members/AMAZGROUP

x-www-form-urlencoded payload

members[0][unique_id]=12345&members[1][unique_id]=67890

Example Output:

{
  "id":5,
  "site_id":1,
  "name":"Amazing Group",
  "slug":"AMAZGROUP",
  "unlisted":0,
  "order":1,
  "created_at":"2020-01-01 00:00:00",
  "updated_at":"2020-01-02 00:00:00",
}

Response Codes

Code	Meaning
200	Success (All Users Removed from Group)
404	Group Not Found
400	Malformed Request (slug missing?)
500	Error Processing Request