Group Web Service

Owned by Chris Hyzer
Last updated: Mar 22, 2011Version comment

Group Operations

Note, these operations are POX, not RESTful so that the operation can be directly mirrored and not altered to fit into a RESTful paradigm.  Authentication is pluggable and not discussed here.

Generally all data is in XML elements (not attributes), naming convention is camel case, and datatypes in the XML schema are strings.  We can easily add JSON or SOAP in the next release.

Shared datatypes

The requestMetadata is standard for all requests.  You specify:

  • clientType: free-form string max 128.  Should be descriptive about which type of client you have, like a browser user-agent
  • clientVersion is the version of the client, should be W.X.Y.Z where W and X and Y and Z are integers
  • protocolVersion is the version of the protocol.  Note, this is probably in the URL as well
  • logLevel: error | warn | info | debug.  The server can do with this what it chooses, though there are some side effects in the response metadata

groupLookup has two possible mutually exclusive subelements

  • groupUri: see group uri from group API
  • groupUuid: see group UUID from group API

subjectLookup has four possible subelements

  • sourceId: optional, to specify where the subject comes from
  • subjectIdOrIdentifier: uniquely identifies a subject (in combination with source), can be an id (12345678), or an identifier (jsmith, or jsmith@school.edu).

responseMetadata

  • serverType: free-form string max 128.  Should be descriptive about which type of client you have, like a browser user-agent
  • requestId: 32 char uuid unique for request.  Could be used to tie to logs etc
  • serverVersion is the version of the server, should be W.X.Y.Z where W and X and Y and Z are integers
  • protocolVersion is the version of the protocol.
  • success: T or F as to whether the request was a success.
  • resultCode: has various possible values depending on the request.  This also might have info about the state of the registry (e.g. if has immediate vs effective memberships etc
  • requestSummary: Sent back in info logLevel or below, free form text, contents not specified.  e.g. Checking has member on group with uri: group:edu:school:folder:folder2:groupName and subject with identifier: someNetId
  • debugSummary: Sent back in debug logLevel, free form text, contents not specified, e.g. Group found, allowed to view members, checking membership, found.</debugSummary>
  • warnings: Sent back in warn logLevel or below if there are warnings, free form text, contents not specified, e.g. Client version is deprecated
  • errors: If "errors" is specified, then the success will be F.  If success is F, then this needs to be filled in.  Free form text contents unspecified
  • serverMillis: integer number of millis representing the processing time on the server.

hasMember()

boolean hasMember(GroupLookup group, Subject subject, enum immediacy=any)

Input

groupHasMemberRequest:

  • requestMetadata (see above)
  • groupLookup (see above)
  • subjectLookup (see above)
<groupHasMemberRequest>
  <requestMetadata>
    <clientType>FIFER Java</clientType>
    <clientVersion>1.0.0.0</clientVersion>
    <protocolVersion>1.0.0.0</protocolVersion>
    <logLevel>warn</logLevel>
  </requestMetadata>
  <groupLookup>
    <groupUri>group:edu:school:folder:folder2:groupName</groupUri>
  </groupLookup>
  <subjectLookup>
    <subjectIdOrIdentifier>someNetId</subjectIdOrIdentifier>
  </subjectLookup>
</groupHasMemberRequest>

Output

groupHasMemberResponse

  • hasMember: T|F
  • responseMetadata (see above)
<groupHasMemberResponse>
  <hasMember>T</hasMember>
  <responseMetadata>
    <serverType>FIFER Java</serverType>
    <requestId>1234567890abcdef1234567890</requestId>
    <serverVersion>1.0.0.0</serverVersion>
    <protocolVersion>1.0.0.0</protocolVersion>
    <success>T</success>
    <resultCode>SUCCESS_HAS_IMMEDIATE</resultCode>
    <serverMillis>345</serverMillis>
  </responseMetadata>
</groupHasMemberResponse>