| Include Page | ||||
|---|---|---|---|---|
|
| Panel | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
|
Grouper Web Services
| Gliffy Diagram | ||||||
|---|---|---|---|---|---|---|
|
| Children Display |
|---|
Introduction
Grouper web services (grouper-ws) is a J2EE web application which exposes common Grouper business logic through SOAP and REST. See Web Services FAQ. and architectural diagram.
...
- Understand the object model. All grouper-ws services are operations based on simple data structures. The structures support Strings, ints, arrays, and structure references.
- Core web service API
- Example structure (only "getters" and "setters" are applicable properties)
- Each operation has many samples (authmated captures, versioned, and up to date). Here is an example
- Most options has a sensible default (e.g. MemberFilter defaults to All members)
- Lookup objects in various (consistent) ways. e.g. to delete a group, you can pass the name or uuid of the group.
- Decide if you are using SOAP or REST (this is real REST, not Axis HTTP/XML)
- Both SOAP and REST support the same API
- Inside SOAP and REST, each operation has two levels of complexity, the normal one, and the Lite one.
- Normal operation: can usually be batched (support a list of inputs, e.g. add multiple groups at once), supports complex inputs (arrays or structures)
- Lite operation: supports only inputs of scalars (no structures, no arrays... only Strings, ints, etc). In REST this also means that the request can be sent via query string only
- If SOAP:
- Implement based on WSDL. Note, you cant get the 1.4 WSDL out of a 2.0 server, since it has backwards compatible changes from 1.5 and 1.6. You could get this 1.4 WSDL from SVN though...
Grouper client version | v1.4, v1.5, v1.6, v2.0 (server version) Endpoint | WSDL from server | WSDL from SVN |
|---|---|---|---|
1.4 | https://server.address/grouperWs/services/GrouperService?wsdl | ||
1.5 | https://server.address/grouperWs/services/GrouperService?wsdl | ||
1.6 | https://server.address/grouperWs/services/GrouperService?wsdl | ||
2.0 | https://server.address/grouperWs/services/GrouperService_v2_0 | https://server.address/grouperWs/services/GrouperService_v2_0?wsdl |
- Note, if your servlet is not grouperWs (e.g. grouper-ws) then adjust accordingly.
- There is a sample Java client with sample calls
- If REST:
- Decide what format you want to send and receive data. grouper-ws supports XHTML, XML, and JSON, as well as query strings for input (in URL or message body)
- For example, in the URL you can set the content type you want back:
| Code Block |
|---|
/grouper-ws/servicesRest/xml/v2_1_000/groups/aStem%3AaGroup/members/10021368
/grouper-ws/servicesRest/json/v2_1_000/groups/aStem%3AaGroup/members/10021368
/grouper-ws/servicesRest/xhtml/v2_1_000/groups/aStem%3AaGroup/members/10021368
|
...
Add a new servlet filter mapping in the web.xml
| Code Block |
|---|
<filter-mapping>
<filter-name>Grouper logging filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
|
Set the filter logger to log at debug level
| Code Block |
|---|
log4j.logger.edu.internet2.middleware.grouper.ws.j2ee.ServletFilterLogger = DEBUG
|
You will see log entries like this
| Code Block |
|---|
2012-05-03 09:13:18,575: [http-8088-1] DEBUG ServletFilterLogger.logStuff(98) - - IP: 127.0.0.1, url: /grouperWs/servicesRest/v2_1_001/groups/aStem%3AaGroup/members, queryString: null, method: PUT, content-type: text/x-json; charset=UTF-8
request params:
request body: {"WsRestAddMemberRequest":{"actAsSubjectLookup":{"subjectId":"GrouperSystem"},"replaceAllExisting":"F","subjectLookups":[{"subjectId":"10021368"},{"subjectId":"10039438"}]}}
respone headers: (note, not all headers captured, and not in this order)
X-Grouper-resultCode: SUCCESS
X-Grouper-success: T
X-Grouper-resultCode2: NONE
HTTP/1.1 201
Content-Type: text/x-json; charset=UTF-8
response: {"WsAddMemberResults":{"responseMetadata":{"millis":"237","serverVersion":"2.1.1"},"resultMetadata":{"resultCode":"SUCCESS","resultMessage":"Success for: clientVersion: 2.1.1, wsGroupLookup: WsGroupLookup[pitGroups=[],groupName=aStem:aGroup], subjectLookups: Array size: 2: [0]: WsSubjectLookup[subjectId=10021368]\n[1]: WsSubjectLookup[subjectId=10039438]\n\n, replaceAllExisting: false, actAsSubject: WsSubjectLookup[subjectId=GrouperSystem], fieldName: null, txType: NONE, includeGroupDetail: false, includeSubjectDetail: false, subjectAttributeNames: null\n, params: null\n, disabledDate: null, enabledDate: null","success":"T"},"results":[{"resultMetadata":{"resultCode":"SUCCESS_ALREADY_EXISTED","success":"T"},"wsSubject":{"id":"10021368","name":"10021368","resultCode":"SUCCESS","sourceId":"jdbc","success":"T"}},{"resultMetadata":{"resultCode":"SUCCESS_ALREADY_EXISTED","success":"T"},"wsSubject":{"id":"10039438","name":"10039438","resultCode":"SUCCESS","sourceId":"jdbc","success":"T"}}],"wsGroupAssigned":{"description":"a group description","displayExtension":"a group","displayName":"a stem:a group","extension":"aGroup","name":"aStem:aGroup","typeOfGroup":"group","uuid":"d9094e4a7c6e4f399d7e1489c875b9f0"}}}
|
...
See the always available client for more info on this slide 
Children pages
| Children Display |
|---|
To do's (post 1.6.0)
- add logging filter
- fix javadoc warnings
- look into axis2 1.5, see if error fixed, see if samples/wsdl changes
- add move subject service
- improve auto-toString methods in resultMessage
- look at acegi
- add ip source filtering to grouper
...