Skip to end of metadata
Go to start of metadata

Base Urls - evaluation and production

  • https://dev.groups.uw.edu/group_sws/v3
  • https://eval.groups.uw.edu/group_sws/v3
  • https://groups.uw.edu/group_sws/v3 – production

API reference

The Groups API v3 is described in this OpenAPI specification:

The "Try it out" button requires some setup in your browser:

  1. You must load a UWCA certificate into your browser for use as a client certificate.
    1. Interactions will be authenticated as the Subject of your client certificate.
  2. Once you have loaded a UWCA certificate, browse to the OpenAPI:
    1. https://iam-tools.u.washington.edu/apis/gws/
  3. Click the "Server" menu to choose an environment:
    1. dev.groups.uw.edu
      1. Uses test data in a "dev" environment
      2. No further setup necessary because it uses an InCommon certificate (trusted by your browser)
    2. eval.groups.uw.edu
      1. Uses a previous copy of test data in a "eval" environment
      2. No further setup necessary because it uses an InCommon certificate (trusted by your browser)
    3. groups.uw.edu – recommended
      1. Uses production data in the Groups service
      2. No further setup necessary because it uses an InCommon certificate (trusted by your browser)
    4. iam-ws.u.washington.edu – deprecated
      1. Uses production data in the Groups service
      2. You must load the UWCA root certificate into your browser as a trusted certificate

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.

LDAP cache issues - eventual consistency

The group service uses LDAP caches to improve reliability and response time for some requests: membership and searches. The caches may take several seconds to update. This can cause inconsistency in that you may not 'read what you wrote' during that time.

There are two ways to achieve consistency:

  • Tell the update API to wait until the caches are updated before returning a response.
    • Query string parameter: synchronized
  • Tell the query API to bypass the cache and use the registry.
    • Query string parameter: source=registry
  • The UI presently uses the synchronized approach to cache consistency unless you are signed in with 2FA.


Community Contributions

The following applications/code/samples/etc. have been submitted by the community of API users.  These contributions have not been reviewed for security vulnerabilities or best practices.  Please contact the authors with questions about code from this section.

  • https://github.com/uwwebservices/groups-mgmt - Parses all direct members of a group's subgroups (one level deep) and adds them to a separate UW group.  e.g. add all members of uw_pottery_* (one level deep) to uw_pottery_users. 

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.

  • No labels