Grouper Developers Forum

[Scotty Logan <>]

[I had not looked at grouper in a long time... took a look recently
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
see Grouper embrace REST properly - if not, it should really call the
API what it is: RPC over HTTP.

TL;DR version: go watch the Apigee videos -
http://www.youtube.com/apigee - probably some of the best videos about
REST and web services.

On Tue, 31 Jul 2012, Chris Hyzer wrote:
> I wish REST were more conducive to the operations that I envision needed by 
> a groups API.

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

> I think the important thing is HTTPS and JSON (or some formatting), not 
> that the URL is the noun and the HTTP method
> is the verb.

Again, you're misunderstanding the architecture of REST.  The URL is
not a noun, it's a sequence of plurals and identifies, with some
option filters (expressed as query parameters).  The URL refers to a
resource.  The body contains a representation of a particular state of
that resource (or collection of resources).  The method (verb) states
what to do with the body and URL; depending on the method, the request
body may be empty while the response body is not, or the reverse, or
both the request and the response may have a body.

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

> Some gaps that I see that make REST awkward for groups are:
> 1. There is more than one way to refer to objects (UUID, system name, gid?, 
> etc), whereas in URLs its nice if there is just one thing like a name

It's nice, but it's not required by REST.

GET /groups/1234/members/12 ... could return a representation of a
specific member of the group, or it return a redirect to another
resource.  The only requirement is that the API handles such requests
consistently.  If GET /foo/1234/bar/12 returns a redirect to the
resource that describes the member, GET /bar/1234/foo/12 should also
return a redirect to a resource.

You can also use search for the other names (see below), and return
canonical URLs for the resource (NOT object).

>> 2. Some things have composite keys: e.g. subjects are sourceId+subjectId, 
>> or sourceId+subjectIdentifier, or just subjectId maybe, again, not 
>> conducive to URL

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.

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

> 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

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

> 4. We have a SOAP RPC based version of grouper WS and it is nice if the 
> rest-like and SOAP are the same except for data formatting.

This just leads to bad REST APIs.  REST APIs should be designed as
façades to hide the internal implementation and to make sense to the
developers using the API.


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

> Or (possible to do something like this with grouper)
> POST https://server.institution.edu/grouper/rest
> (body)
> {addMemberLiteRequest:{
>    groupName:"a:b:c",
>    sourceId:"person",
>    subjectId:"12345"
>  }
> }

Which is the same as the one above.  Truly RESTful would be

POST /groups/a:b:c/members
Content-type: application/json

[ "/person/12345" ]

> Another idea we had with FIFER is that the full
> featured API could be HTTPS/JSON, but there could be a RESTful one too which
> was limited (e.g. only used system names to refer to things) that would be
> in line with then RESTful mindset...

No, a limited API would not be in line with the "RESTful mindset."  A
full API designed around well-thought out resources and linkages
between them would be in line with the "RESTful mindset."

  Scotty