Introduction

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

Audience

The GWS REST API is a programmable interface, so you are expected to be an application developer. 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.

Overview

The GWS 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 our REST API. Some notes:

  1. Representations may contain additional elements to those describe 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 GWS must have their DNS name registered in UW DNS.

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

Authorization

Connection port

Connecting on port 443 is supported and recommended. Connecting on the alternate port (7443) is also supported but may be deprecated in the future.  Also note that jumbo frames (MTU > 1500) are not supported. 

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.

However, note that:

Classification

A group may be classified, according to the APS 2.6 and UW Data Classification guidelines.

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

Note that:

Membership

Use of POST

The GWS accepts the POST method for two purposes:

  1. URI too long.
    If your uri would be too long for likely transport to the web service you may enclose it in a POST, with the elements:

    <span class="_method"> GET | PUT | DELETE </span>
    <span class="_uri"> uri </span>
    

    included in the POST document.  The path components of you actual URL must match those in the posted "_uri".

  1. PUT content too big
    If your PUT content would be too big for likely transport to the web service you may enclose it in a POST, with the element:

    <span class="_method">PUT</span>
    

    included in the POST document.

Conventions

Sample Code

Groups Web Service Resources

Versions

GWS supports version v1 and v2. Version 2 supports the authnfactor, classification, membership dependency (dependson), and optin and optout ACLS.

API customers can find the new v3 JSON documentation: https://wiki.cac.washington.edu/display/infra/Group+Service+v3+API

Get a group
Create a group
Update a group
Delete a group

Get membership
Get effective membership
Update membership
Delete membership

Get member(s)
Get effective member
Add member(s)
Delete member(s)

Search

Get history

Get an affiliate
Set an affiliate
Delete an affiliate

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