Skip to content

Graphene Group Sync

Jump to bottom
Tim Cortesi edited this page Apr 9, 2019 · 8 revisions

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

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
by Adam Smallcomb and Tim Cortesi
in collaboration with Binghamton University and Escher Labs, Inc.
Clone this wiki locally