Connectors for groups¶
This document is not final, but work in progress.
The Group connector is configured with a base URL, such as:
https://api-group-datasource.no/groups
Authentication¶
Serverside TLS, HTTP Basic Authentication or Client certificate.
The Protocol¶
All requests are HTTP GET requests, and all responses MUST be JSON encoded.
Some endpoints may offer parameters passed through with a query string.
List of group protocol endpoints
Endpoint | Protocol description | Data returned |
---|---|---|
v1/{userid}/groups | The group memberships of a specific user | List of groups |
v1/{userid}/groups/{groupid} | One user's membership of one group | One membership object |
v1/groups/{groupid} | Details about a group | One group object |
v1/groups/{groupid}/members | Members of a group | A list of users |
v1/groups | List all public groups | A list of groups |
The userid
is provided in the following format:
feide:olanormann@uninett.no
. The FeideID will normally be used to
look up groups, but the syntax allows for other types of userids.
Dataporten will for example make use of national identity numbers
nin:10107012345
in some use cases.
The groupid
s need to be globally unique, and include a prefix that
allows the group engine to know which backend gruop connector to use to
retrieve additional information from the group.
When a group connector is set up for a specific institution, it may
agree upon a prefix with Dataporten, such as fc:g:ntnu.no:cerebrum
or fc:g:uhad
. Each group provided through these connectors must
include the prefix in the identifier, in example
fc:g:ntnu.no:cerebrum:idi:298387467
. These examples are
illustrative, just to show the idea, typically one should avoid using
systemspecific names within the identifier, making it easier to replace
a connector with a new conector leaving the group identifier intact.
The group memberships of a specific user¶
Returns a list of group objects. If groups have a start or end date, only return active groups.
Query string parameters:
showAll=true
return also inactive groups (e.g. with a passed end date){ "meta": {}, "items": [ {group}, {group}, {group} ] }
The users membership to a specifc group is embedded in the
membership
property when groups are listed. Here is an example of a group object:{ "id": "fc:org:uninett.no:unit:avd-u20", "type": "fc:orgunit", "displayName": "Avdeling for System og Mellomvare", "norEduOrgAcronym": "ASM", "public": true, "mail": "asm@uninett.no", "membership": { "basic": "admin", "displayName": "Ansatt", "affiliation": ["employee", "member"], "primaryAffiliation": "employee" } }
One user’s membership of one group¶
TBD
Details about a group¶
TBD
Members of a group¶
{
"meta": {},
"items": [
{user}, {user}, {user}
]
}
Example of a user object:
{
"userid_sec": ["feide:andreas@uninett.no"],
"name": "Andreas \\u00c5kre Solberg",
"email": "andreas.solberg@uninett.no"
}
List all public groups¶
TBD
Data model¶

The groups data model
A user is a member of a set of groups. For each group the user is a member of, the membership is represented with the existence of a membership object. The membership object has no required properties, but a set of optional properties.
Properties of the group object are specific to the group and are the same for all members, while properties of the membership object are specific to each member.
All groups share some common properties, while there is a set of group type definitions that define extended attributes for different kind of groups.
For each configured group connector, a list of allowed group types is defined. New group types may be defined and documented. It is important to avoid that for a given user the same semantic group is reflected in two duplicate groups (typically spanning multiple group connectors).