Re: Re: New Internet-Draft: JSON Hypertext Application Language

On Wed, Feb 13, 2013 at 9:59 AM, Mike Kelly <[email protected]> wrote:

> Hi Craig,
>
> Thanks for your response.
>
> The problem with that approach is you have to force your access model
> around the HTTP verbs. So if you have different transitions possible for a
> PUT or POST request on a given resource, and each have different access
> rules, then you're out of options (no pun intended).
>
Well, my task was to define public HTTP APIs for our resources, so binding
to HTTP semantics didn't really bother me :-).


> Another approach is to create permission resources that represent the
> roles the requesting user has for particular activities. The roles can be
> more descriptive, flexible, and intuitive to clients that way.
>
> Are there some compelling reasons to work around HTTP that i'm missing.
>
> Along the same lines, I'm a bit concerned about absorbing HTTP stuff into
> the media type. Which I think this technique is guilty of. A while back I
> considered adding etag info for embedded resources but canned it because of
> the same concern.. Out of interest how would you feel about that etag
> approach?
>
I think there are (at least) two things to consider:

* Syntax/semantics for defining permissions

* In band (that is, part of the resource representation)
  or out of band (in an HTTP case, typically transmitted
  via headers).

For the 'permissions' concern, a trivial extension to what I suggested
would be to allow arbitrary values for the "allowed" field, which could be
role names with semantics that are agreed upon between client and server.
 For a client that *is* using HTTP, that would then require some
understanding of how to map roles to HTTP verbs.  For our use case, we use
the verbs consistently and conventionally across all of our endpoints (POST
to a collection URI == create, PUT to an individual endpoint == update, and
so on), so we're relying on the client to understand that convention -- but
it seems easier to understand, at least for simple CRUD type operations.

On the topic of in band versus out of band, the latter would probably be
more "pure" -- but in band is much easier for client developers to deal
with.  They have to access the JSON or XML or whatever content of the
response body anyway.  Requiring them to deal with HTTP headers or whatever
as well is extra work.

I know of at least one effort[1] to formalize out of band link
relationships with better semantic information ("rel") -- but this still
doesn't address the issue of "what can this particular client do with this
URI"?

Craig

[1] http://tools.ietf.org/html/draft-snell-link-method-01


>  Cheers,
> M
>
> On 13 Feb 2013 17:35, "Craig McClanahan" <[email protected]> wrote:
> >
> > I've written several APIs lately that contain a similar concept to the
> "links" abstraction with a useful extension -- we also include an "allowed"
> field that contains an array of the HTTP verbs that this user is allowed to
> perform against the URL specified by "href".  Essentially, we're saving the
> client the need to do an OPTIONS call to determine what verbs are supported
> for that user.
> >
> > A use case for this is when displaying content that may or may not be
> editable (or can be deleted) by the requesting user.  If so, the "allowed"
> field would say '[ "GET", "PUT", "DELETE" ]'.  If not, it would just say '[
> "GET" ]'.  A client UI can use this information to decide whether or not to
> display enabled "Edit" or "Delete" buttons.
> >
> > Craig McClanahan
> >
> > On Tue, Feb 12, 2013 at 1:52 PM, Mike Kelly <[email protected]>
> wrote:
> >>
> >>
> >>
> >> Here's a slightly more useful link than the previous one!
> >>
> >> http://tools.ietf.org/html/draft-kelly-json-hal-05
> >>
> >> On Tue, Feb 12, 2013 at 7:53 AM, Mike Kelly [email protected]>
> wrote:
> >> > Hello all,
> >> >
> >> > fyi, I have updated the following internet draft:
> >> >
> >> > http://www.ietf.org/id/draft-kelly-json-hal-04.txt
> >> >
> >> > All thoughts, comments, suggestions, etc welcome
> >> >
> >> > Cheers,
> >> > Mike
> >>
> >> --
> >> Mike
> >>
> >> http://twitter.com/mikekelly85
> >> http://github.com/mikekelly
> >> http://linkedin.com/in/mikekelly123
> >>
> >> 
> >
> >
>
>