Groups API endpoints¶
The protocol is a simple, lightweight REST-ish protocol.
The group endpoints require that you provide a valid access token with scopes for appropriate
attribute groups. groups-edu
, groups-org
and groups-other
are attribute groups For
different kinds of groups.
The base URL prefix of all group related endpoints on Feide is:
https://groups-api.dataporten.no/groups/
List of group protocol endpoints
Endpoint |
Protocol description |
Data returned |
---|---|---|
The group memberships of the current user |
List of groups |
|
My membership of this particular group |
One membership object |
|
Details about a group |
One group object |
|
Members of a group |
A list of users |
|
List all groups |
A list of groups |
|
List all group types |
A list of group types |
The group memberships of the current user me/groups
¶
Requests need to be authenticated with a personal token.
This endpoint returns all active group memberships of the current user. Expired or otherwise inactive groups are not returned by default.
Query string parameters:
showAll=true
The provider will list all groups that the current user is associated with, also expired and inactive groups and roles.
The response contains a list of groups. If the user is not a member of
any active groups, an empty list is returned; []
. If the token isn’t bound
to a user, 403 Forbidden is returned.
Here is an example of a response body:
GET /groups/me/groups HTTP/1.1
Host: groups-api.dataporten.no
Authorization: Bearer 0f0935c3-a997-40fb-89c2-f7da126ba5d9
200 OK
Content-Type: application/json; charset=utf-8
Content-Language: no
[
{
"id": "fc:adhoc:8878ae43-965a-412a-87b5-38c398a76569",
"displayName": "...",
"...": "..."
},
{
"id": "fc:adhoc:8878ae43-965a-412a-87b5-38c398a76569",
"displayName": "....",
"...": "..."
}
]
For the specifications of the attributes of groups, review the group type specifications:
My membership of this particular group /me/groups/{groupid}
¶
Requests need to be authenticated with a personal token.
If the user is a member of the specified group, this endpoint returns the membership object representing the user’s relation to the group.
GET /groups/me/groups/fc%3Aadhoc%3A8878ae43-965a-412a-87b5-38c398a76569 HTTP/1.1
Host: groups-api.dataporten.no
Authorization: Bearer 0f0935c3-a997-40fb-89c2-f7da126ba5d9
200 OK
Content-Type: application/json; charset=utf-8
Content-Language: no
{
"basic": "member"
}
If the access token doesn’t allow access to the group or the token isn’t bound to a user, the endpoint returns 403 Forbidden. If the user isn’t a member of the group, 404 Not Found is returned.
Details about a group /groups/{groupid}
¶
Requests need to be authenticated with a token.
This endpoint returns details about a group that the user has access to. The user may have access to view information about the group even if the user is not member. For example, the group information might be public.
GET /groups/groups/fc%3Aadhoc%3A8878ae43-965a-412a-87b5-38c398a76569 HTTP/1.1
Host: groups-api.dataporten.no
Authorization: Bearer 0f0935c3-a997-40fb-89c2-f7da126ba5d9
200 OK
Content-Type: application/json; charset=utf-8
Content-Language: en
{
"id": "fc:adhoc:8878ae43-965a-412a-87b5-38c398a76569",
"displayName": "Project on group APIs",
"type": "voot:ad-hoc"
}
If the access token doesn’t allow access to the group, the endpoint returns 403 Forbidden. If the user isn’t a member of the group or the token isn’t bound to a user, the response from the endpoint is as follows:
Group type |
Response |
---|---|
fc:adhoc (public) |
group data |
fc:adhoc (private) |
404 Not Found |
fc:fs |
404 Not Found |
fc:gogroup |
404 Not Found |
fc:grep |
group data |
fc:org |
404 Not Found |
Members of a group /groups/{groupid}/members
¶
Requests need to be authenticated with a token.
This endpoint returns all *active* group members of the specified group. Expired or otherwise inactive members will not returned by default.
GET /groups/groups/fc%3Aadhoc%3A8878ae43-965a-412a-87b5-38c398a76569/members HTTP/1.1
Host: groups-api.dataporten.no
Authorization: Bearer 0f0935c3-a997-40fb-89c2-f7da126ba5d9
Query string parameters:
showAll=true
The provider will list all members that are associated with the group, also expired and inactive user memberships.
The response contains a list of users. If the group does not currently
have any members, an empty list is returned; []
.
Some group types do not support listing members. In these cases an empty list is returned.
Normally, user IDs are not returned for the users when listing group members. However, when the attribute group groups-memberids is configured and the group backend supports it, the user ID is returned in a userid_sec attribute. This attribute group is moderated by Sikt. Currently, this attribute group is supported by the backend for primary and secondary education in Norway.
Here is an example of a response body:
[
{
"name": "Andreas Åkre Solberg",
"membership": {
"basic": "member"
}
},
{
"name": "Anders Lund",
"membership": {
"basic": "admin"
}
},
{
"name": "Olav Morken",
"membership": {
"basic": "member"
}
}
]
Example, with user IDs included:
[
{
"name": "Alf Berg",
"userid_sec": [
"feide:aberg04@elgskinnetskole.sunnvik.kommune.no"
],
"membership": {
"affiliation": "student",
"basic": "member",
"displayName": {
"nb": "Elev"
}
}
},
...
{
"name": "Eva Vesthus",
"userid_sec": [
"feide:evesthus01@elgskinnetskole.sunnvik.kommune.no"
],
"membership": {
"affiliation": "student",
"basic": "member",
"displayName": {
"nb": "Elev"
}
}
}
]
If the access token doesn’t allow access to the group, the endpoint returns 403 Forbidden. If the user isn’t a member of the group or the token isn’t bound to a user, the response from the endpoint is as follows:
Group type |
Response |
---|---|
fc:adhoc (public) |
list of members |
fc:adhoc (private) |
403 Forbidden |
fc:fs |
both members and nonmembers receive an empty list |
fc:gogroup |
404 Not Found |
fc:grep |
both members and nonmembers receive an empty list |
fc:org |
both members and nonmembers receive an empty list |
List all (or query a set of) groups /groups
¶
Requests need to be authenticated with a token.
The response is a list of group objects. If no groups were found or the token
isn’t bound to a user, an empty list is returned: []
.
With no query string, the list contains the following groups:
Groups the user belongs to
Public adhoc groups
There is limited support for querying.
Query string parameters (optional):
query={search}
When a query string is given, the result shown above is restricted as follows:
Groups of some types are dropped. Only the following types are included:
Adhoc groups (
fc:adhoc
)Groups for primary and secondary education (
fc:gogroup
)Organization groups (
fc:org
)Organization unit groups (
fc:orgunit
)
Groups are included when the query parameter is a substring of the displayName. For adhoc groups, matches in description also count. Search is case sensitive, except for group type
fc:gogroup
. Group IDs aren’t used when searching.
Here is an example of a response body, to a request for the search term «Mat»:
GET /groups/groups?query=Mat HTTP/1.1
Host: groups-api.dataporten.no
Authorization: Bearer 0f0935c3-a997-40fb-89c2-f7da126ba5d9
[
{
"id": "fc:adhoc:e7074db1-acb2-4165-b53e-6a48fa1019f4",
"displayName": "Matteskatt",
"type": "voot:ad-hoc",
"public": true,
"description": "Matematikk for alle."
},
{
"id": "fc:gogroup:spusers.feide.no:u:NO856326499:1amat:2021-07-01:2022-06-30",
"displayName": "Matematikk 1A",
"type": "fc:gogroup",
"...": "..."
}
]
List all group types /grouptypes
¶
This endpoint is used to return information about group types.
It will at least return group type information for all group types represented by the groups that the current user is a member of.
The response contains a list of group types. If no group types was
found, an empty list is returned; []
.
Here is an example of a response body:
GET /groups/grouptypes HTTP/1.1
Host: groups-api.dataporten.no
Authorization: Bearer 0f0935c3-a997-40fb-89c2-f7da126ba5d9
[
{
"id": "voot:adhoc", "displayName": "Ad-hoc group"
},
{
"id": "fc:org", "displayName": "Organization"
},
{
"id": "fc:emne", "displayName": "Subject"
}
]
Group identifiers in URLs¶
Group identifiers are used as path elements in URLs. The group
fc:gogroup:spusers.feide.no:b:NO856326499:6a:2021-07-01:2022-07-30
represents a group
in lower education in Norway. Here is how to retrieve it:
GET https://groups-api.dataporten.no/groups/groups/fc%3Agogroup%3Aspusers.feide.no%3Ab%3ANO856326499%3A6a%3A2021-07-01%3A2022-07-30
The group ID may contain ‘%’ or other special characters. You have to encode these before you use them in a URL. E.g. turn ‘6%20a’ into ‘6%2520a’.
The reason is that whenever a web server encounters a ‘%’ in a URL, it interprets it as the start of an encoded character. The urls
https://www.example.org/hi
and https://www.example.org/h%69
are actually the same URL. The Group API will only see a ‘%’ if
it is encoded to ‘%25’.
The group ID should be percent encoded as specified in the rules for path segments in RFC 3986. The characters that do not need encoding according to this standard are ‘A-Z’, ‘a-z’, ‘0-9’, ‘-’, ‘.’, ‘_’ and ‘~’. For the groups API, ‘:’ can also be left unencoded.