Fetching Groups via the API

Groups provide a means to organise multiple accounts collectively. The OpenAthens user administration interface allows operations to be performed on groups of accounts. Currently, the API provides only limited support for groups.

Fetching a group

The group(s) an individual account is a member of is returned as part of the application/vnd.eduserv.iam.account-v1+json object. Further information about a group can be obtained by fetching a group object.

Prerequisites

To fetch group information, a client application must

authenticate to the API as described in Authenticating to the API.
obtain an account object, or a list of groups for an organisation.

Procedure

Perform a GET request to a group resource.

/api/v1/example.org/group/<id>

This returns a application/vnd.eduserv.iam.admin.group-v1+json object.

Response codes

HTTP Response Code	Description
200	The request was successful.
400	The request was invalid.
404	The group does not exist.

Example

Request:
GET /api/v1/example.org/group/1234 HTTP/1.1
Authorization: OAApiKey <api-key>
Response (success):
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.admin.group-v1+json
 
{
    "id": "1234",
    "name": "group1",
    "links" : [
                { "rel" : "up",
                  "type" : "application/vnd.eduserv.iam.admin.organisation-v1+json",
                  "href" : "/api/v1/example.org/organisation/1234",
                  "method" : "get"
                }
              ]
}

application/vnd.eduserv.iam.admin.group-v1+json object

Object field	Description
name	The name of the group.

Listing groups

Groups belong to and are created by organisations. Therefore an application/vnd.eduserv.iam.admin.organisation-v1+json object provides a link to a resource that will return a list of groups for that organisation.

Prerequisites

To fetch group information, a client application must

authenticate to the API as described in Authenticating to the API.
obtain an organisation object, as described in Fetching organisations via the API.

Procedure

Follow the link from an organisation object with a media type of application/vnd.eduserv.iam.admin.groupList-v1+json by performing a GET request to:

/api/v1/example.org/organisation/<id>/groups

The response payload is a list of groups.

Response codes

HTTP Response Code	Description
200	The request was successful.
400	The request was invalid.
404	The organisation does not exist.

Example

Request:
GET /api/v1/example.org/organisation/1234/groups HTTP/1.1
Authorization: OAApiKey <api-key>
Response (success):
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.admin.groupList-v1+json
 
{
    "groups": [
        { "name" : "group1", "href" : "/api/v1/example.org/group/1234" },
        { "name" : "group2", "href" : "/api/v1/example.org/group/5678" },
        { "name" : "group3", "href" : "/api/v1/example.org/group/9012" },
        { "name" : "group4", "href" : "/api/v1/example.org/group/3456" }
    ],
    "links" : [
                { "rel" : "up",
                  "type" : "application/vnd.eduserv.iam.admin.organisation-v1+json",
                  "href" : "/api/v1/example.org/organisation/1234",
                  "method" : "get"
                }
              ]
}