Workgroup RESTful Web Services API

HTTP Status codes

Code Conditions
200 OK The usual successful return code.
400 Bad Request Missing required parameters or identifier is in wrong format.
403 Access Denied The request was made without valid certificate.
404 Not Found The record you're looking for doesn't exist.
500 Internal Server Error Something broke with our code. Please tell us about it.

Error handling

Workgroup API sends error status via standard HTTP status codes (4xx) and always returns an XML document detailing the error. For example when client makes a call to update a workgroup filter with not supported filter value, system will return following XML error document.

PUT https://workgroupsvc.stanford.edu/v1/workgroups/mais:new/filter
Content-Type:text/plain;charset=UTF-8
Content-Length:9

XXXX_XXXX

HTTP/1.1 400 Bad Request
Date:Sat, 01 Aug 2009 18:35:51 GMT

<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>400</code>
    <message>Filter value "XXXX_XXXX" not supported</message>
</error>

Get Workgroup

Description Get workgroup
URL https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}
Method GET
Query string -none-
Returns 200 OK & workgroup XML
404 Not Found
If authenticated user is an administrator of the workgroup, return XML document include public (description, filter, visibility, privgroup and reusable) and private (members and administrators) information. If authenticated user is not an administrator of the workgroup, return XML document includes only public information of the workgroup. Please note that "authenticated user" may refer to a certificate name, in which case the certificate needs to be configured as a workgroup administrator.

GET https://workgroupsvc.stanford.edu/v1/workgroups/mais:test

HTTP/1.1 200 OK
Content-Disposition:attachment; filename="mais:test.xml"
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:534
Date:Sat, 01 Aug 2009 18:25:48 GMT

<?xml version="1.0" encoding="UTF-8"?>
<workgroup>
    <description>Test workgroup</description>
    <filter>FACULTY_STAFF_STUDENT</filter>
    <visibility>PRIVATE</visibility>
    <reusable>TRUE</reusable>
    <privgroup>TRUE</privgroup>
    <members>
        <member name="user1" url="https://workgroupsvc.stanford.edu/v1/users/user1"/>
        <member name="user2" url="https://workgroupsvc.stanford.edu/v1/users/user2"/>
        <workgroup name="workgroup:mais" url="https://workgroupsvc.stanford.edu/v1/workgroups/workgroup:mais"/>
        <workgroup name="workgroup:mais-dev" url="https://workgroupsvc.stanford.edu/v1/workgroups/workgroup:mais-dev"/>
    </members>
    <administrators>
        <member name="user3" url="https://workgroupsvc.stanford.edu/v1/users/user3"/>
        <member name="user4" url="https://workgroupsvc.stanford.edu/v1/users/user4"/>
        <workgroup name="mais-staff" url="https://workgroupsvc.stanford.edu/v1/workgroups/mais-staff"/>
    </administrators>
</workgroup>

Create workgroup

Description Create workgroup
URL https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}
Method POST
Request Content Type text/xml;charset=UTF-8
Request Body(optional): XML
Sample request body XML:
<workgroup>
    <description>Test workgroup</description>
    <filter>
   {NONE|ACADEMIC_ADMINISTRATIVE|STUDENT|FACULTY|
   STAFF|FACULTY_STAFF|FACULTY_STUDENT|
   STAFF_STUDENT|FACULTY_STAFF_STUDENT}
</filter>
    <visibility>{PRIVATE | STANFORD}</visibility>
    <reusable>{ TRUE | FALSE }</reusable>
    <privgroup>{ TRUE | FALSE }</privgroup>
</workgroup>

Following are default values:-
description={empty string}. If description contains more than 255 characters, first 255 characters used (maximum 255 characters)
filter=NONE
visibility=STANFORD
reusable=TRUE
privgroup=FALSE
Returns 200 OK
400 Bad Request
401 Unauthorized
409 Conflict
Please note that authenticated user has to be an administrator of the workgroup, return XML document include public (description, filter, visibility, privgroup and reusable) and private (members and administrators) information. If authenticated user is not an administrator of the workgroup, return XML document includes only public information of the workgroup. Please note that "authenticated user" may refer to a certificate name, in which case the certificate needs to be configured as a workgroup administrator.

POST https://workgroupsvc.stanford.edu/v1/workgroups/mais:new
Content-Type:text/xml;charset=UTF-8
Content-Length:195

<workgroup>
    <description>Test workgroup</description>
    <filter>ACADEMIC_ADMINISTRATIVE</filter>
    <visibility>PRIVATE</visibility>
    <reusable>FALSE</reusable>
    <privgroup>TRUE</privgroup>
</workgroup>

HTTP/1.1 201 Created
Server:Apache-Coyote/1.1
Location:/v1/workgroups/mais:new
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:28:35 GMT

Delete workgroup

Description Delete a workgroup
URL https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}
Method DELETE
Query string -none-
Returns 200 OK
400 Bad Request
401 Unauthorized
404 Not Found
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.

DELETE https://workgroupsvc.stanford.edu/v1/workgroups/mais:wgapi

HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT

Add member

Description Add member or workgroup as a workgroup member
URL https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}/members
Method PUT
Query string user=https://workgroupsvc.stanford.edu/v1/users/{sunetid}
user=https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}
Returns 200 OK
400 Bad Request
401 Unauthorized
404 Not Found
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.

PUT https://workgroupsvc.stanford.edu/v1/workgroups/mais:wgapi/members?user=https://workgroupsvc.stanford.edu/v1/workgroups/mais:new

HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT

Remove member

Description Remove member or workgroup from a workgroup
URL https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}/members
Method DELETE
Query string user=https://workgroupsvc.stanford.edu/v1/users/{sunetid}
user=https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}
Returns 200 OK
400 Bad Request
401 Unauthorized
404 Not Found
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.

DELETE https://workgroupsvc.stanford.edu/v1/workgroups/mais:wgapi/members?user=https://workgroupsvc.stanford.edu/v1/workgroups/mais:new

HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT

Add administrator

Description Add member or workgroup as a workgroup administrator
URL https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}/administrators
Method PUT
Query string administrator=https://workgroupsvc.stanford.edu/v1/users/{sunetid}
administrator=https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}
Returns 200 OK
400 Bad Request
401 Unauthorized
404 Not Found
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.

PUT https://workgroupsvc.stanford.edu/v1/workgroups/administrators?administrator=https://workgroupsvc.stanford.edu/v1/workgroups/mais:new

HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT

Remove administrator

Description Remove member or workgroup from a workgroup administrator
URL https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}/administrators
Method DELETE
Query string administrator=https://workgroupsvc.stanford.edu/v1/users/{sunetid}
administrator=https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}
Returns 200 OK
400 Bad Request
401 Unauthorized
404 Not Found
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.

DELETE https://workgroupsvc.stanford.edu/v1/workgroups/administrators?administrator=https://workgroupsvc.stanford.edu/v1/workgroups/mais:new

HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT

Update description

Description Update workgroup description.
If description contains more than 255 characters, first 255 characters used.
URL https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}/description
Method PUT
Request Content Type text/plain;charset=UTF-8
Request Body description
Query string -none-
Returns 200 OK
400 Bad Request
401 Unauthorized
404 Not Found
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.

PUT https://workgroupsvc.stanford.edu/v1/workgroups/mais:new/description
Content-Type:text/plain;charset=UTF-8
Content-Length:16

Test Description

HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT

Update filter

Description Update workgroup filter (overwrite existing filter value with new filter value)
URL https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}/filter
Method PUT
Request Content Type text/plain;charset=UTF-8
Request Body filter value
Query string -none-
Returns 200 OK
400 Bad Request
401 Unauthorized
404 Not Found
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.

Supported filter values are:
  • ACADEMIC_ADMINISTRATIVE
  • STUDENT
  • FACULTY
  • STAFF
  • FACULTY_STAFF
  • FACULTY_STUDENT
  • STAFF_STUDENT
  • FACULTY_STAFF_STUDENT
  • NONE
PUT https://workgroupsvc.stanford.edu/v1/workgroups/mais:new/filter
Content-Type:text/plain;charset=UTF-8
Content-Length:24

ACADEMIC_ADMINISTRATIVE

HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT

Update reusable property

Description Update workgroup reusable property - this indicates whether the workgroup can be nested.
URL https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}/reusable
Method PUT
Request Content Type text/plain;charset=UTF-8
Request Body reusable value i.e {TRUE | FALSE}
Query string -none-
Returns 200 OK
400 Bad Request
401 Unauthorized
404 Not Found
409 Conflict
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.

PUT https://workgroupsvc.stanford.edu/v1/workgroups/mais:new/reusable
Content-Type:text/plain;charset=UTF-8
Content-Length:5

FALSE

HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT

Update visibility property

Description Update workgroup visibility property
URL https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}/visibility
Method PUT
Request Content Type text/plain;charset=UTF-8
Request Body visibility value i.e {PRIVATE | STANFORD}
Query string -none-
Returns 200 OK
400 Bad Request
401 Unauthorized
404 Not Found
409 Conflict
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.

PUT https://workgroupsvc.stanford.edu/v1/workgroups/mais:new/visibility
Content-Type:text/plain;charset=UTF-8
Content-Length:8

STANFORD

HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT

Update privgroup property

Description Update workgroup privgroup property
URL https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}/privgroup
Method PUT
Request Content Type text/plain;charset=UTF-8
Request Body privgroup value i.e {TRUE | FALSE}
Query string -none-
Returns 200 OK
400 Bad Request
401 Unauthorized
404 Not Found
409 Conflict
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.

PUT https://workgroupsvc.stanford.edu/v1/workgroups/mais:new/privgroup
Content-Type:text/plain;charset=UTF-8
Content-Length:5

FALSE

HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT