Group Membership Service 1.0 WD

[Mark Taylor]

Hi Brian.

Responses to responses:

On Fri, 23 Nov 2018, Brian Major wrote:

> On Thu, Nov 22, 2018 at 5:01 AM Mark Taylor <M.B.Taylor at bristol.ac.uk>
> wrote:
> 
> > Brian,
> >
> > On Fri, 2 Nov 2018, Brian Major wrote:
> >
> > First, the the "search API" defines two functions:
> >
> >    boolean isMember(Group, User)
> >    list<Group> getMemberships(User)
> >
> > and these are implemented by the REST API under the endpoints:
> >
> >    GET /search/{group}
> >    GET /search
> >
> > Unless I'm misunderstanding what's going on here (possible),
> > it seems a bit unnecessarily confusing to give these completely
> > different names in the abstract API and the REST interface.
> >
> 
> Right.  The first set of 'functions' was really just a way for me to work
> through what features are needed by the search API.  The second set is the
> translation of those features to REST.  This obviously came across as
> confusing so perhaps the first set of features should be removed... ?
> 
> Would it be better to homogenise them a bit, e.g.
> >
> >    GET /gms/isMember/{group}
> >    GET /gms/getMemberships
> >
> 
> I see what you're saying but a homogenized version doesn't seem RESTful.
> 'search' in the path is intended to identify a resource, but this is a
> stretch because 'search' is really more of an operation.  Also, 'search'
> serves as a way of namespacing the API.  I can see GMS supporting other
> capabilities at some point.  For example, to manage groups and membership,
> you may have something like 'GET /groups/{group}.  Anyhow, I'm certainly
> open to suggestions on how this API should be denoted.

OK I must admit that how to do REST is not something I've really paid
attention to beyond figuring that it's something to do with using HTTP.
This was just my initial reaction - if on consideration you still like
it the way you have it, that's fine by me.

> > Second, the way in which HTTP return codes are used to communicate
> > results seems slightly fishy.
> >
> > The text says:
> >
> >    "An HTTP GET to /search/{group} shall respond with HTTP 200 (OK) if
> >     the user is a member of the {group}. If the user is not a member of
> >     the group, or if the user is not recognized, or if the group is not
> >     recognized, the service shall respond with HTTP 403 (Forbidden)."
> >
> > This looks funny to me, since the request is to find out whether
> > a given user is a member of a named group, and a positive or
> > negative answer is being given - in the case of no membership,
> > the request about membership is not being forbidden (403) it's
> > just being answered in the negative.  The forbidden-ness doesn't
> > really apply to this response, just to the responses that a user
> > with the given identity might expect if s/he tries to do something
> > auth-sensitive in the future.
> >
> 
> Yes, I agree--this is not using HTTP response codes as intended.
> 
> 
> >
> > Moreover, RFC2616 section 10.4.4 says this about the 403 Forbidden
> > response code:
> >
> >    "The server understood the request, but is refusing to fulfill it.
> >     Authorization will not help and the request SHOULD NOT be repeated."
> >
> > But in the case of this endpoint, authorization might help, since
> > in the case where the request specifies the queried user's identity
> > implicitly (i.e. no user/principal request parameters supplied),
> > resubmitting the request with different credentials would
> > constitute a query about a different user, so might very well
> > give a different result.
> >
> 
> Another good point.
> 
> 
> >
> > So, maybe communicating the result using the (text/plain?) payload
> > of a 200 response might be more appropriate than communicating
> > the result using the HTTP response code.
> >
> 
> Okay, so I agree it needs to change.  I think we have a number of
> alternatives (for a GET to /search/{group})
> 
> 1.  For non error situations, always return HTTP 200 OK.
> 
>     Variant A:  text/plain response: Return the single group name if the
> user is a member, return an empty document if not.  (This is consistent
> with the GET /search behaviour.)
> 
>     Variant B:  text/plain response with 'true' if the user is a member and
> 'false' if the user is not a member.
> 
>     Variant C:  Return an XML document with an element that describes the
> group.  This is like Variant A but would allow the response to be extended
> by evolving the XML schema if we find there is more information about the
> group that needs to be conveyed.  With this approach we'd apply this
> pattern to GET to /search as well.

I like the idea of making the responses consistent for the two methods,
so 1A looks nice.  Steering clear of XML where it's not needed is IMHO
a good plan.  But, like you say, 1C would give more flexibility.
I can't think of extra information that would be required here,
but other GWS members might have a better idea about that.
 
> 2.   If the user is a member of the group, return HTTP 200 OK.  If the user
> is not a member of the group, return HTTP 204 No Content.  Maybe this is a
> violation of the HTTP rules too.  In its definition, this line I found
> interesting:
> 
>     "This response is primarily intended to allow input for actions to take
> place without causing a change to the user agent's active document view,
> although any new or updated metainformation SHOULD be applied to the
> document currently in the user agent's active view."

I can see that using these response codes does make the result
determination easy and unambiguous from certain contexts.
However, I can imagine that if you want to invoke this service
e.g. from a browser or a shell script it could be less straightforward
to retrieve the response code, so I'd be inclined to use content instead.
Just my opinion!

Mark

--
Mark Taylor   Astronomical Programmer   Physics, Bristol University, UK
m.b.taylor at bris.ac.uk +44-117-9288776  http://www.star.bris.ac.uk/~mbt/