Groups API Questions - Protocol

Questions

1. Initial assumption is web service based with pluggable authentication
   1. Which authentication should we support?  SSL cert, ws-auth, user/pass in http basic auth, public key signature in http header, other?
2. Do we need a messaging design (xmpp)?
3. REST? (if REST, then XML, JSON, and/or XHTML)?
4. SOAP?
5. Simple calls vs Batched calls (e.g. replace all members of a group with the attached list)?  (if batched, can you pass a TX type e.g. use a transaction or not)?
6. Simple responses or complex responses (e.g. for groups a subject is in, return just the ID (KIM) or return group information(Grouper))?
7. How are results communicated back?  Result code, description, warnings, errors, success_TF, etc?
8. If you add a member to a group who is already a member, is that a success, and is there a result code that represents that? (same with delete)
9. Paging and sorting for results?
10. Is the client and server version transmitted in the request/response?
11. Should operations be idempotent?  i.e. if an operation is executed twice, should be a success both times (e.g. add member, create group)

COmanage responses

For the most part, details aren't that important to COmanage. In general, simpler is better.

1. COmanage is concerned about keeping admin tasks to a minimum (since they'll already be a lot of them), so eg user/pass is easier to manage than SSL certs.
2. Possibly, both for Gears (if backsync from the group manager is allowed) and for domesticated Apps.
3. REST is good, XML or JSON.
4. Gears isn't using SOAP, so would rather not need it.
5. Simple probably.
6. No opinion.
7. No, it's a failure.
8. Not needed.
9. Probably.
10. Isn't this basically the same as #8?

Grouper responses

1. Pluggable authentication is ideal. user/pass that delegates to kerberos is needed, also user/pass in http basic auth, at least
2. Messaging: This seems like it would be useful, but hasn't taken off that much in Grouper, so we should at least plan for it in the future
3. REST? (if REST, then XML, JSON, and/or XHTML): I think we should focus first on the object types that are passed back and forth, and we can see what translations we need to convert that to a plain text HTTPs protocol... this is how Grouper works to support so many formattings
4. SOAP: Would prefer to start with REST-like
5. Either is fine, though having a replace operation is nice (which takes a list of users)
6. Simple responses or complex responses: If there is a "Subject Service"or whatever service to get at the data, then simple responses are fine.  It is useful in Grouper to have complex responses, though there is more complexity
7. How are results communicated back?  Result code, description, warnings, errors, success_TF, etc?  I like the grouper model, where there are some HTTP headers, a success T/F, a response code, message, etc
8. If you add a member to a group who is already a member, is that a success, and is there a result code that represents that? (same with delete): Operations should definitely be idempotent... if an operation is invoked twice, it should not be a failure (e.g. a client might think there is a timeout and resubmit, then it might get processed twice).  However, result codes should be descriptive
9. Paging and sorting for results?  If this service is used for UI's, then we need it.  And if we have it, we definitely need a Subject Service
10. Is the client and server version transmitted in the request/response?  We should plan for versioning, which includes transmitting the versions back and forth.
11. Should operations be idempotent?  i.e. if an operation is executed twice, should be a success both times (e.g. add member, create group)

Rice responses

NAU responses

1. user/pass in https is sufficient, but pluggable would be nice.
2. ?
3. REST is fine.
4. Not necessary.
5. It depends on the kind of call. In a user interface, add/mod/delete of groups is usually one at a time, so can be simple. Member management is usually many at a time so should be batched. Not sure what is meant by "can you pass a TX".
6. Complex. Maybe an option to return simple or complex info on per call basis.
7. Prefer errors and warnings with code and description. Success can be a simple code.
8. It is a success, but there should be info returned to reflect the difference (i.e different result code from success, not already a member). The more granular the return info is, the better. The user can decide whether the difference is relevant to their application.
9. Paging not necessary as part of the interface. Paging needs seem very application-specific. Sorting not necessary, but would be nice if sort field can be specified (e.g. group id vs group name vs other group attribute).
10. Don't have a need for it now.
11. Yes, but result code should reflect any differences per 8.

uPortal Responses

1. We approve of pluggable authentication in general with a decent selection of options.
   1. Which authentication should we support?  SSL cert, ws-auth, user/pass in http basic auth, public key signature in http header, other?
2. Not sure we have a need for messaging right now
3. Yes, we'd very much want REST support. Either XML or JSON would be fine.
4. We'd prefer REST to SOAP.
5. Simple calls would be nice to have, but we might want batched support with transactions for larger or more complex operations.
7. I think we'll need known response codes for programmatic handling of success and errors, but it would be useful to have a readable description to go along with that.
8. Yes, it should be successful, and yes, there should be a code to differentiate these events.
9. Yes, paging and sorting would be useful.

Etc