Groups Service API

Introduction

This guide describes the Groups Service REST API (Groups API) as used by programmatic clients. It does not describe the Groups user interface (UI) offered to browser users.

Audience

The Groups API is a programmable interface, so you are expected to be an application developer.

Overview

The Groups API offers a "RESTful" programmatic interface. It exposes groups and group information as addressable resources via the uniform HTTP interface.

Authorized clients may retrieve (GET), update (PUT) and delete (DELETE) representations of these resources through the API.

Client applications must be able to connect to the web service using HTTPS and authenticate using SSL/TLS authentication with an X.509 certificate.

Conventions

Some conventions used in our documentation:

• {text} means that "{text}" should be replaced with a specific name or identifier.
• (root) should be replaced by the base URL of the service. For our production service it is:
  • https://groups.uw.edu/group_sws/( v1 | v2 | v3)

• {type} is a member type: uwnetid|group|dns|eppn|uwwi.

Some conventions used in the API itself:

1. Representations may contain additional elements to those described here.
2. GET representations are similar to PUT representations.
3. Many responses include an ETag header.  Where indicated, a corresponding If-Match header with the same data must accompany a PUT request.
4. Content is identified by a microformat: class, id and type attributes and by text content. Element names are ignored.

Security and access control

Authentication

Clients authenticate with X.509 certificates issued by the UW Services Certificate Authority and are identified by the Subject of the certificate: specifically, the DNS name included in the Common Name (CN) value or any Subject Alt Names.

Hosts connecting to the Groups API must have their DNS name registered in UW DNS.

The Groups API also identifies itself with a server certificate issued by the same authority.

Authorization

• Authorization decisions are based on the authenticated identity of the client (see Authentication above).
• In order to edit group information, excluding membership, or to delete a group a client must have Admin privilege on the group.
• In order to add or remove members a client must have Admin or Update privilege on the group.
• In order to create a group a client must have Admin or Create privilege on nearest stem of the group.
• In order to view a group's membership a client must have Admin, Update or Read privilege on the group, or the group must be flagged as "read-all".
• In order to view the basic information of a group a client must have Admin, Update, Read or View privilege on the group, or the group must be flagged as "read-all" or "view-all".
• By default, all Personal UW NetIDs have Admin privilege on their own, possibly non-existing, base stem (u_ userid ).

• Some clients may assume the privileges of, and act for, another user. This is accomplished by adding an act-as header to a request:

  X-UW-Act-as: user's_ePPN

Connection port

Connecting on port 443 is recommended and required for off campus access. Connecting on the alternate port (7443) is deprecated but supported for legacy campus access.  Also note that jumbo frames (MTU > 1500) are not supported.

Your application must be able to connect to the web service using HTTPS and authenticate using SSL/TLS authentication with an X.509 certificate. It must be able to make HTTP GET, PUT, and DELETE requests to the service as needed.

Authentication factor

A group may be configured to require 2-factor authentication for update operations including PUT and DELETE operations on the general information, membership, or application information.

• This feature is referred to in the Groups UI using an "enable enhanced security" checkbox.
• The API attribute class is "authnfactor" and has a value of 1 or 2.

However, note that:

• A group with an authnfactor of 2 cannot be updated via the API.
• The authnfactor attribute is available starting with API version 2.

Classification

A group may be classified according to APS 2.6 and Data Classification Process.

The API attribute class is "classification" and may have the values:

• 'u' = unclassified
• 'p' = public
• 'r' = restricted
• 'c' = confidential

Notes:

• Groups UI access to the membership of confidential groups requires 2-factor authentication.
• The classification attribute is available starting with API version 2.

Membership

• Direct Members: Groups have several types of direct members:

  UWNetID	A simple UWNetID, e.g. abcde
  EPPN	A fully qualified eduPersonPrincipalName, e.g.  abcde@example.edu
  DNS	A UWCA certificate's common name or subjectAltName, e.g. abcde.washington.edu
  Group	Name of another group, e.g. u_abcde_friends
  MI	A Microsoft Infrastructure AD machine name

• Effective members: An effective member is either a direct member of the group or an effective member of a member group

Large membership changes

If you are making large membership changes, say more than a few hundred, your experience will be better if you split your activity into adds or deletes of fifty to a hundred members at a time.  This tends to give you immediate feedback on successful changes and avoids possible session or connection timeouts.

API Resources

Versions

Groups API supports version v1, v2 and v3 (recommended). 

Contact Us

Email help@uw.edu to contact the staff in UW-IT who oversee this wiki space and the groups service.

Announcements : Join groups-announce@uw.edu for service announcements.

Discussion : Discuss the service with other customers and users on groups-users@uw.edu.