Grouper Developers Forum

[Chris Hyzer <>]

> for a project and learned that the "RESTful" API is still in the same
> state it was years ago... far, far from being RESTful].  I'd love to

We try not to refer to it as "restful".  We say rest-like or http pox or 
whatever...  there are URL's in the WS that refer to resources something like 
rest...

e.g. if you

GET /grouper-ws/servicesRest/json/v2_1_001/subjects/10021368/groups HTTP/1.1

That will give you all the groups the user is in for Grouper.  Though the 
response is the WsGetGroupsLiteResult object which cannot be sent back to the 
server.  
If you

GET /grouper-ws/servicesRest/v2_1_001/groups/aStem%3AaGroup/members HTTP/1.1

That will give you the members of the aStem:aGroup group in Grouper, and it 
will give you the group object too.  Again, you cant send that request back 
to add a member...

So parts of it can be like REST... :)

We didn't go crazy in the URLs... if you want to refer to a group by uuid, 
you need to do that in params, I think you can put the subject sourceId in 
the URL, don't remember.

> 
> You're thinking about REST the wrong way.  SOAP is about operations -
> making remote procedure calls to modify remote objects.  REST (as
> "REpresentational State Transfer" implies) is about the client and
> server exchanging representations of resources (which may or may not
> have a direct mapping to the underlying objects).

Right, well, when you have SOAP and something non-soap (restful or 
json/http), then if they are the same there are economies of scale in the 
maintenance, documentation, and ability to understand/use them.  If we didn't 
have SOAP too, the restlike would have been different.

> Think of this more like SQL insert, update, delete, select statements
> rather than stored procedure calls.

The last operation I added (well, almost done) is a way to batch up attribute 
assignments/unassignments into one operation for performance reasons.  Your 
analogy is good with insert/update and stored procedures... sometimes stored 
procs are useful.

> There are plenty of ways to represent that in a URL... the API
> developers just need to pick one (or a few) and use them consistently:
> 
> /source/{sourceId}/subject/{subjectId} -> 200 + subject
> representation, or 404, etc.
> /source/{sourceId}?subjectId={subjectId} -> 200 + array of subject
> representations, or 404, etc.
> /source/?sourceId={sourceId}&subjectId={subjectId} -> 200 + array of
> subject representations, or 404, etc.
> /source/?subjectId={subjectId} -> 200 + array of subject
> representations, or 404, etc.

Yeah, the URL path implies a hierarchy to me, and a membership being a 
groupName or ID, optional listName, user sourceId (optional), subjectId or 
identifier, maybe other stuff (point in time? Immediate or effective or 
composite, membership id? Etc.  it seems to me to make more sense to have 
something like this:

{addMembership:{
  groupLookup:{
    groupName: "a:b:c"
  },
  listName: members,
  subjectLookup: {
    sourceId: "person",
    subjectId: "1234"}
  }
}

The addMembership is documented in the WSDL, and the addMembership bean, its 
easy to know whats available etc.  The JSON doesn't imply hierarchy, is the 
URL a group with list and member or a user with group and list or a user with 
list and group?  I guess one redirects to the other if many are supported but 
it seems like a headache

Sometimes whats read from the server is different than what you write to the 
API.  In Grouper we make it a lot more efficient e.g. when you request 
memberships, it sends back the membership objects, the group objects and the 
subject objects (and maybe other things) so you don't have to followup the 
membership call with 2*N other calls to get useful data.  Well, some of this 
stuff you can opt-out of or opt-in in the request for performance reasons. 
i.e. in Grouper you can get all the email addresses of members from a 
membership call, or you can get all the group descriptions.  But you cant 
change the group name or user's email address in a membership add call.

> 
> > 3. GET,PUT,POST,DELETE are limiting, and I don't think it is a good idea 
> > to make up custom methods, and GET can't send a request?
> 
> GET is a request, it's just a read-only request.  Expecting otherwise
> is the same as expecting SELECT to change a table.

Right, one of the operations in Grouper is to get groups and send in 100 
group ids to get in one request.  The JSON sent to the server is posted since 
it might be large.  But it is still a readonly request...

> 
> > Can all browsers or user agents do PUT and DELETE?
> 
> Most of the ones we care about nowadays.  Others can do POST +
> X-HTTP-Method-Override header:
> 
> POST /groups/12
> X-HTTP-Method-Override: DELETE

That's good to know about

> 
> If a tool can't use PUT and DELETE, and can't set a custom header...
> you need better tools.

Agreed, custom header read is assumed in Grouper WS, you can write a 
content-type but its not required to be able to write...

> 
> > I don't really see why:
> >
> > (RESTful add member)
> > PUT
> > https://server.institution.edu/grouper/rest/group/systemName/a:b:c/member/subjectSourceId/person/subjectId/12345
> 
> That's RESTful: the URL is the representation of the membership
> (although it's a bloated URL).
> 
> >> Is any easier/intuitive than (possible to do something like this with
> >> grouper):
> >> POST
> >> https://server.institution.edu/grouper/rest?operation=addMemberLite&groupName=a:b:c&sourceId=person&subjectId=12345
> 
> That's a representation of an action to create a group membership -
> it's not a representation of a group membership.  If you're going to
> use representations of actions rather than resources, you might as
> well use SOAP.
> 

Right, Im just saying that HTTP/JSON is similar in the transport/formatting 
so it can be used by ajax a lot easier than soap.  I know its not restful, 
but its not all that much different and each one might be easier or more 
difficult for different people but either is doable since the technologies 
are compatible...

Im not saying that restful is bad, but I am saying that for groups and access 
management I think we need more than just insert/update/delete, I think we 
need stored procs.  I don't mind having restful on top of the rpc service, 
though I don't see it being as full-featured, since for certain things you 
might have to make more requests to do the same thing or get the same data... 
 also it might only be for Lite operations.  i.e. can you insert/update 
multiple groups at once with restful?  We have a group save option where you 
can specify insert/update/insert_or_update.  Is that possible with put/post?  
It is with stored procs but not insert/update :)

If we want the standard API to be restful, that's fine, lets try it out and 
see how we do, especially if there is no SOAP version also.  If there is a 
way to also have RPC type stuff which is HTTP/json where requirements dont 
fit into restful, that is good too :)

Thanks,
chris


did anyone make it this far? :)