The Grouper webservice exposes the functionality of the Grouper API over a webservice interface. It supports both SOAP and REST style calls.
Simple Object Access Protocol (SOAP) was designed as a standardisation of Remote Procedure Calls, working over HTTP and HTTPS. A SOAP message consists of an envelope, containing the message data, with the whole thing formatted as XML. A SOAP web service typically publishes a document which describes the methods is offers, using the Web Services Description Language (WSDL). A clilent can parse this document in order to understand what calls can be made and how to make them. Typically a set of client classes are built which represent stubs to methods on the remote server. These classes can be used by developers without them needing to know anything about the internals of SOAP. SOAP is cross-platform, so a java web service can be consumed by a client developed in another programming language (such as PHP, Perl, .NET etc).
Representational State Transfer (REST) is designed to be simpler than SOAP, and more suitable for use by clients which do not support (or want to support) SOAP client functionality. These clients may be AJAX (Asynchronous JavaScript and XML) pages in a rich web client, mobile phones, kitchen appliances or whatever. REST uses URIs (unique resource locators) to identity resources and the basic verbs of HTTP (GET, POST, PUT, DELETE) to express the operation requested, whears SOAP typically uses a POST to a single URI, with all resource and operation information held within the message. This means that REST can use URIs, querystring and post parameters to package both the method requested and the data being transmitted. REST is also relatively unconvered about the format uses to format the data, supporting formats such as HTML, XML and JSON. This flexibility makes it attractive to bleeding-edge developers. Typically, a REST service does not publish a document describing what it offers, so documentation is required to enable clients to be developed.
Whether you choose SOAP or REST will not be determined by Grouper since it supports both, but by your preferrences and the nature of you implementation. ASs a rule of thumb: the more complex you client, and the more methods it needs to call, the more likely you are to use SOAP; the simpler your client (perhaps it only ever makes one type of call), the more likely you are to choose REST which should work more efficiently on the client.
Building the Grouper Webservice
Before building the webservice, I will assume that you have completed the following:
- Configured a repository database for Grouper
- Configured a source for Grouper subjects
- Built the Grouper API (which is turn required Ant and Java)
- Successfully tested the Grouper API
- Have Apache Tomcat installed and working. If installed using a download from apache.org then make a note of the base directory of the Tomcat installation. I'll refer to is as TOMCAT_HOME. If yoiu bave installed using a package from another source your layout may well be different, with directories spread out accross the file system. You will need to indentify where the Tomcat conf directory is (and use it for TOMCAT_HOME/conf), where webapps are installed (and use it for TOMCAT_HOME/webapps) and where the logs are written (and use this for TOMCAT_HOME/logs).
You should have the files contained in GROUPER_HOME used for the API build available on the machine on which you are building the webservice.
- Download the Grouper Webservice tarball from http://www.internet2.edu/grouper/software.html
- Extract the tarball to a directory, I will refer to this as GROUPER_WS_HOME
- Open the file GROUPER_WS_HOME/grouper-ws/build.properties and edit the following:
grouper.dir - set it to your GROUPER_HOME, this will mean other file paths relative to grouper.dir will be correct
tomcat.dir - set it to your TOMCAT_HOME (N.B. need to check what this does). This is optional, you can leave it as the default.
tomcat.port - set it to the port your tomcat server is lisenting on the HTTP requests. This is optional, you can use it as the default. - Open a command line and navigate to GROUPER_WS_HOME/grouper-ws
- Enter the command ant - this will build the webservice server and client components, using your existing Grouper coniguration files for the repository and source data connections
The webservice server web application will now be built as a web archive in GROUPER_WS_HOME/grouper-ws/build/dist/grouper-ws.war. An exploded archive can be found at GROUPER_WS_HOME/grouper-ws/build/grouper-ws. Install the application by either copying the grouper-ws.war to TOMCAT_HOME/webapps/, or creating a file in TOMCAT_HOME/conf/Catalina/localhost called grouper-ws.xml with the following content:
| Code Block |
|---|
<Context path="/grouper-ws" reloadable="true" docBase="GROUPER_WS_HOME/grouper-ws/build/grouper-ws/"/> |
Restart tomcat and, assuming there are no errors showing up, you now have the Grouper Webservice running.
Authentication to the webservice:
The webservice is configured to require tomcat to supply a username to the webapp. By default this is done in the same way as for the Grouper UI - basic auth managed by Tomcat. You can use the same tomcat-users.xml as for the quickstart, install it into TOMCAT_HOME/conf and restart Tomcat if it's not already there. You can now authenticate to the webservice using username: GrouperSystem password:123.
Testing with a client.
TBC, see the CXF client page for now
Further information:
https://spaces.at.internet2.edu/display/Grouper/Grouper+Web+Services