DRAFT

Summary

This documents the implementation of one operation of the groups API. There is a reference implementation server which makes it easy to implement the FIFER protocol.

hasMember operation

Note: this is similar to what we already discussed, though as it was implemented, things were tweaked. Of course we should discuss the discrepancies :)
This is an outline of the object model. Each FIFER transport (REST, POX, POJ, SOAP) uses this object model.

Input:

GroupHasMemberRequest
- groupLookup : GroupLookup
  - handle: String
  - id: String
- immediacy : String (immediate, nonimmediate, any[default])
- subjectLookup : SubjectLookup
  - handle: String
  - id: String
  - idOrHandle: String
  - subjectSource: String

Output:

GroupHasMemberResponse
- hasMember
- responseMetadata: ResponseMetadata
  - errorText: String
  - protocolVersion: String
  - requestId: String
  - resultCode: Sring
  - serverMillis: int
  - serverType: String
  - serverVersion: String
  - success: boolean
  - warnings: String

SOAP

This is the CXF WSDL from the service interface

<?xml version='1.0' encoding='UTF-8'?>
<wsdl:definitions name="fiferService_v0_1"
    targetNamespace="http://ws_v0_1.fiferServer.fifer.jasig.org/"
    xmlns:ns1="http://schemas.xmlsoap.org/soap/http" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:tns="http://ws_v0_1.fiferServer.fifer.jasig.org/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <wsdl:types>
        <xs:schema elementFormDefault="unqualified"
            targetNamespace="http://ws_v0_1.fiferServer.fifer.jasig.org/"
            version="1.0" xmlns:tns="http://ws_v0_1.fiferServer.fifer.jasig.org/"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
            <xs:element name="hasMember" type="tns:hasMember" />
            <xs:element name="hasMemberResponse" type="tns:hasMemberResponse" />
            <xs:complexType name="hasMember">
                <xs:sequence>
                    <xs:element minOccurs="0" name="groupLookup" type="tns:groupLookup" />
                    <xs:element minOccurs="0" name="subjectLookup" type="tns:subjectLookup" />
                    <xs:element minOccurs="0" name="immediacy" type="xs:string" />
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="groupLookup">
                <xs:sequence>
                    <xs:element minOccurs="0" name="handle" type="xs:string" />
                    <xs:element minOccurs="0" name="id" type="xs:string" />
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="subjectLookup">
                <xs:sequence>
                    <xs:element minOccurs="0" name="handle" type="xs:string" />
                    <xs:element minOccurs="0" name="id" type="xs:string" />
                    <xs:element minOccurs="0" name="idOrHandle" type="xs:string" />
                    <xs:element minOccurs="0" name="subjectSource" type="xs:string" />
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="hasMemberResponse">
                <xs:sequence>
                    <xs:element minOccurs="0" name="return"
                        type="tns:groupHasMemberResponse" />
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="groupHasMemberResponse">
                <xs:sequence>
                    <xs:element name="hasMember" type="xs:boolean" />
                    <xs:element minOccurs="0" name="responseMetadata" type="tns:responseMetadata" />
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="responseMetadata">
                <xs:sequence>
                    <xs:element minOccurs="0" name="errorText" type="xs:string" />
                    <xs:element minOccurs="0" name="protocolVersion" type="xs:string" />
                    <xs:element minOccurs="0" name="requestId" type="xs:string" />
                    <xs:element minOccurs="0" name="resultCode" type="xs:string" />
                    <xs:element name="serverMillis" type="xs:int" />
                    <xs:element minOccurs="0" name="serverType" type="xs:string" />
                    <xs:element minOccurs="0" name="serverVersion" type="xs:string" />
                    <xs:element name="success" type="xs:boolean" />
                    <xs:element minOccurs="0" name="warnings" type="xs:string" />
                </xs:sequence>
            </xs:complexType>
        </xs:schema>
    </wsdl:types>
    <wsdl:message name="hasMember">
        <wsdl:part element="tns:hasMember" name="parameters">
        </wsdl:part>
    </wsdl:message>
    <wsdl:message name="hasMemberResponse">
        <wsdl:part element="tns:hasMemberResponse" name="parameters">
        </wsdl:part>
    </wsdl:message>
    <wsdl:portType name="FiferGroupService">
        <wsdl:operation name="hasMember">
            <wsdl:input message="tns:hasMember" name="hasMember">
            </wsdl:input>
            <wsdl:output message="tns:hasMemberResponse" name="hasMemberResponse">
            </wsdl:output>
        </wsdl:operation>
    </wsdl:portType>
    <wsdl:binding name="fiferService_v0_1SoapBinding" type="tns:FiferGroupService">
        <soap:binding style="document"
            transport="http://schemas.xmlsoap.org/soap/http" />
        <wsdl:operation name="hasMember">
            <soap:operation soapAction="" style="document" />
            <wsdl:input name="hasMember">
                <soap:body use="literal" />
            </wsdl:input>
            <wsdl:output name="hasMemberResponse">
                <soap:body use="literal" />
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:service name="fiferService_v0_1">
        <wsdl:port binding="tns:fiferService_v0_1SoapBinding" name="FiferGroupServiceImplPort">
            <soap:address location="http://localhost:8090/fiferServer/services/group_v0_1" />
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

Sample request:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<ns2:hasMember xmlns:ns2="http://ws_v0_1.fiferServer.fifer.jasig.org/">
			<groupLookup>
				<handle>someHandle</handle>
			</groupLookup>
			<subjectLookup>
				<id>someId</id>
			</subjectLookup>
		</ns2:hasMember>
	</soap:Body>
</soap:Envelope>

Sample response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<ns2:hasMemberResponse xmlns:ns2="http://ws_v0_1.fiferServer.fifer.jasig.org/">
			<return>
				<hasMember>true</hasMember>
			</return>
		</ns2:hasMemberResponse>
	</soap:Body>
</soap:Envelope>

REST

This is like POJ/POX but has a simplified request interface

Method	GET
URL	`/groups/<groupid>/members/<memberid>[?immediacy=<immediacy>]`
Request Body	None

Response:

{
  "groupHasMemberResponse":{
    "hasMember":true,
    "responseMetadata":{
      "protocolVersion":"v0.1.0",
      "requestId":"abcd123412345678909",
      "resultCode":"SUCCESS",
      "serverMillis":123,
      "serverType":"FIFER reference server",
      "serverVersion":"v0.5.0",
      "success":true
    }
  }
}

POJ (plain old json)

This is similar to REST, except it doesnt use HTTP methods, and it doesnt use the URL to convey request information (though you could use request params)

Request:

{{
  "groupHasMemberRequest":{
    "groupLookup":{
      "handle":"someHandle"
    },
    "subjectLookup":{
      "id":"someId"
    }
  }
}

Note: you could also use URL params: http://url/fiferServer/poj/v0_1_0?operation=groupHasMemberRequest&groupLookup_handle=someHandle&subjectLookup_id=someId

Response:

{
  "groupHasMemberResponse":{
    "hasMember":true,
    "responseMetadata":{
      "protocolVersion":"v0.1.0",
      "requestId":"abcd123412345678909",
      "resultCode":"SUCCESS",
      "serverMillis":123,
      "serverType":"FIFER reference server",
      "serverVersion":"v0.5.0",
      "success":true
    }
  }
}

POX (plan old xml)

Request:

{<groupHasMemberRequest>
  <groupLookup>
    <handle>someHandle</handle>
  </groupLookup>
  <subjectLookup>
    <id>someId</id>
  </subjectLookup>
</groupHasMemberRequest>

Note: you could also use URL params: http://url/fiferServer/pox/v0_1_0?operation=groupHasMemberRequest&groupLookup_handle=someHandle&subjectLookup_id=someId

Response:

<groupHasMemberResponse>
  <responseMetadata>
    <serverType>FIFER reference server</serverType>
    <requestId>abcd123412345678909</requestId>
    <serverVersion>v0.5.0</serverVersion>
    <protocolVersion>v0.1.0</protocolVersion>
    <success>true</success>
    <resultCode>SUCCESS</resultCode>
    <serverMillis>123</serverMillis>
  </responseMetadata>
  <hasMember>true</hasMember>
</groupHasMemberResponse>

Fifer group server implementation

DRAFT

Summary

hasMember operation

SOAP

REST

POJ (plain old json)

POX (plan old xml)