Skip to Content.
Sympa Menu

grouper-dev - Re: [grouper-dev] re grouper next steps

Subject: Grouper Developers Forum

List archive

Re: [grouper-dev] re grouper next steps


Chronological Thread 
  • From: Scotty Logan <>
  • To: Chris Hyzer <>
  • Cc: Jim Fox <>, Grouper Dev <>
  • Subject: Re: [grouper-dev] re grouper next steps
  • Date: Tue, 31 Jul 2012 15:41:01 -0700

[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



Archive powered by MHonArc 2.6.16.

Top of Page