The VOOT API allows a client to obtain information about the current users group membership from an VOOT Provider.

Authentication

All authenticated protocol requests towards the VOOT Provider MUST be authenticated with an OAuth 2.0 Bearer Token.

This token with either represent an authenticatet client and end-user, or only an authenticated client. Some of the protocol endpoints will require a personal token.

Localization of strings

When the protocol returns objects with properties of type translatable strings, the default behaviour is to negotiate which language to return the string using standard HTTP content negotation. This behaviour can be overriden by adding the query string parameter translate=false.

To illustrate we can look at the following request:

GET /groups/1?translate=false HTTP/1.1
Host: voot-provider.example.org
Authorization: Bearer 1234-asdf-5678

200 OK
Content-Type: application/json; charset=utf-8 

{
	"id": "1",
	"displayName": {
		"en": "Example",
		"no": "Eksempel"
	}
}

as opposed to the default of using HTTP language negotiation:

GET /groups/1 HTTP/1.1
Host: voot-provider.example.org
Accept-Language: da, no;q=0.8, en;q=0.7
Authorization: Bearer 1234-asdf-5678

200 OK
Content-Type: application/json; charset=utf-8 
Content-Language: no

{
	"id": "1",
	"displayName": "Eksempel"
}

Caching and detecting modifications

VOOT Providers should use cache headers as specified in the HTTP specificaiton, in order to signal that the content of the response is unmodified according to a requested timestamp or etag.

Protocol

All API endpoints may contain a custom prefix. The documentation should specify the API base. In example a URL base could be: https://voot-provider.example.org/voot.

Summary

EndpointProtocol descriptionData returned
/me/groupsThe group memberships of the current userList of groups
/me/groups/{groupid}My membership of this particular groupOne membership object
/groups/{groupid}Details about a groupOne group object
/groups/{groupid}/membersMembers of a group A list of users
/groupsList all groupsA list of groups
/grouptypesList all group typesA list of grouptypes

If the VOOT provider allows the client to inspect groups relations for a users that is not represented by the OAuth token, in example by using a token obtained by client credentials only, the following additional endpoint aliases may be used:

EndpointProtocol descriptionData returned
/user/{userid}/groupsThe group memberships of the specified userList of groups
/user/{userid}/groups/{groupid}A specified users membership of this particular groupOne membership object

These endpoints behaves identical to the /me/* endpoints.

The group memberships of the current user /me/groups

Requests needs to be authenticated with a personal token.

This endpoint returns all active group memberships of the current user. Expired or otherwise inactive groups and not returned by default.

GET /me/groups HTTP/1.1
Host: voot-provider.example.org
Authorization: Bearer 1234-asdf-5678

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.

By appending the query string parameter showAll=true to the request,

The response contains a list of groups. If the user is not actively member of any groups, an empty list is returned; [].

Here is an example of a response body:

[
	{
		"id": "8878ae43-965a-412a-87b5-38c398a76569",
		"displayName": "Project on group APIs",
		"membership": {
			"basic": "member"
		}
	},
	{
		"id": "e01eafb1-5f1c-4992-fcd5-ab0160c7ad24",
		"displayName": "Course M.201 Mathematics at University of Oslo",
		"description": "Second year mathematics at the university",
		"active": true,		
		"notBefore": "2006-08-01T12:00:00Z",
		"public": true,
		"sourceID": "voot:sources:uninett:fs",
		"membership": {
			"basic": "member",
			"affiliation": "student",
			"may": {
				"listMembers": true
			}
		},
		"type": "voot:groupTypes:edu:courses"
	}
]

My membership of this particular group /me/groups/{groupid}

Requests needs to be authenticated with a personal token.

If the user is member of the specified group, return the membership object representing the users relation to that group.

GET /me/groups/8878ae43-965a-412a-87b5-38c398a76569 HTTP/1.1
Host: voot-provider.example.org
Authorization: Bearer 1234-asdf-5678

200 OK
Content-Type: application/json; charset=utf-8 
Content-Language: no

{
	"basic": "member",
	"displayName": "Medlem"
}

Details about a group /groups/{groupid}

Requests needs to be authenticated with a token, if needed in order to access the content.

This endpoint returns details about a group, that that user has access to. The user might have access to view information about the group even if the user is not member. In example, the group information might be public.

GET /me/groups/8878ae43-965a-412a-87b5-38c398a76569 HTTP/1.1
Host: voot-provider.example.org
Authorization: Bearer 1234-asdf-5678

200 OK
Content-Type: application/json; charset=utf-8 
Content-Language: en

{
	"id": "8878ae43-965a-412a-87b5-38c398a76569",
	"displayName": "Project on group APIs",
}

Members of a group /groups/{groupid}/members

Requests needs to be authenticated with a token, if needed in order to access the content.

This endpoint returns all *active* group members of the specified group. Expired or otherwise inactive members will not returned by default.

GET /groups/8878ae43-965a-412a-87b5-38c398a76569/members HTTP/1.1
Host: voot-provider.example.org
Authorization: Bearer 1234-asdf-5678

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 is not currently having any members, an empty list is returned; [].

Here is an example of a response body:

[
	{
		"name": "Andreas Åkre Solberg",
		"email": "andreas.solberg@uninett.no",
		"profilePhotoURL": "http://core.feideconnect.no/profile/1234-5678"
		"membership": {
			"basic": "member"
		}
	},
	{
		"name": "Anders Lund",
		"membership": {
			"basic": "admin"
		}
	},
	{
		"name": "Olav Morken",
		"membership": {
			"basic": "member"
		}
	}
]

List all (or query a set of) groups /groups

Requests needs to be authenticated with a token, if needed in order to access the content.

This endpoint is used to return information about groups that the user is not neccessarily member of. It may be used for getting information about other groups that a user may choose to grant access to content in an ACL, or it may be used for initating a request to join a group.

Query string parameters (optional):

query={search}
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 no groups was found, an empty list is returned; [].

Here is an example of a response body, to a request for the search term «UNINETT»:

GET /groups?query=UNINETT HTTP/1.1
Host: voot-provider.example.org
Authorization: Bearer 1234-asdf-5678
[
	{
		"id": "1234-5678", "displayName": "UNINETT Systemavdelingen"
	},
	{
		"id": "1234-5689", "displayName": "UNINETT Tjenesteavdelingen"
	},
	{
		"id": "1234-5690", "displayName": "UNINETT Nettavdelingen"
	}
]

List all group types /grouptypes

This endpoint is used to return information about group types.

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 /grouptypes HTTP/1.1
Host: voot-provider.example.org
[
	{
		"id": "voot:adhoc", "displayName": "Ad-hoc group"
	},
	{
		"id": "eduorg:org", "displayName": "Organization"
	},
	{
		"id": "feide:course", "displayName": "Course"
	}
]