Groups API Questions - Protocol

Owned by Chris Hyzer
Last updated: Jan 11, 2011 by EricEVersion comment

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)

Kuali responses

  1. Agreed that pluggable authentication would be good.  I wonder though how much the API spec should constrain the authentication/authorization method being used to interact with the service and how much of that should be a concern left to the implementor of the API?  Basic HTTP authentication seems like an obvious one.  Digital signatures is also useful.  I think it makes sense that the caller of the service should need to transmit information about their identity because the implementation of the group service may need to use that information to make a decision on whether the particular client is allowed to invoke certain operations, or do we just make this all or none?
  2. I don't know much about this particular topic, so I would be curious to hear about what the benefit would be.
  3. So, my take on this is that we need to first start by defining the data model for a group and the various service operations that will supported as part of the API.  From there, we can add a specification of what this data looks like in an XML format (schema) and from there we can construct WSDL which defines a contract for soap-based services.  Then we can define the contract for a REST api, which would include the URI specifications as well as the data formats which could use the same XML schema.  If we wanted to support a JSON format for REST then we could spec that out as well, but I would consider each of these to be an "extension" or "supplement" to the specification of the general data attributes and the supported operations (i.e. FIFER-Soap, FIFER-REST, etc.)  It could also be done in a different order if we wanted to tackle REST first instead of SOAP.  No real preference here, sounds like others prefer REST.
  4. see my comment above
  5. Good question, I think in certain cases bulk operations can be important.  I'm not sure though if those should be part of the core api or not.  We don't have many use cases I know of at the moment in Kuali for bulk operations via the api but that's not to say those won't come up at some point in the future.  We do actually provide for such things through something we call the "ingester" which allows for people to construct large XML files which include things like Groups and feed them into the system that way, but that sits on top of our APIs currently and invokes multiple service operations over and over again which is probably not the most efficient approach.  Bulk operations would help us out in these cases.
  6. Not sure I have a preference here really.  Complex responses are probably more flexible, but depending on the size of the response there's a question of efficiency.  Not sure it would be a huge problem with a data structure as simple as groups (assuming that every call doesn't return a full list of all members on the group!)
  7. Would this depend in some part on the protocal?  In SOAP it's via faults, in REST it's via http response codes?
  8. I would say it shouldn't be an error (should strive for idempotency where possible), but could you just return an indicator (i.e. true/false) indicating if the member was actually added?
  9. For operations which might return a large set of results, this is probably important (i.e. retrieving all members of a group).
  10. I think versioning is important so this should be considered.
  11. This might depend on the operation?  For example, if someone tries to create a group that already exists, that seems like a failure case to me.  The only case I would consider where that should be idempotent is if they tried to create a group that already exists and they pass the exact same information as the current group with that name (or whatever the unique identifier for groups is, not sure if we've discussed that yet).  I think when looking at a RESTful api, you would use a PUT operation for create and the PUT operation is supposed to be idempotent if you pass the exact same message (REST gurus please correct me if I'm mistaken)

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.
  6.  
  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.
  10.  
  11.  

Etc