Group Membership Service 1.0 WD

[Brian Major]

Hi Mark,

Thanks for your comments, replies below...

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.


>
> 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.

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."

Cheers,
Brian
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.ivoa.net/pipermail/grid/attachments/20181123/6e849c3c/attachment.html>