Subject: [apps-discuss] New Internet-Draft: JSON Hypertext Application Language

From: Mike Kelly <[email-masked]>
Date: Tue, 12 Feb 2013 07:53:29 +0000

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

---

From: Mike Kelly <[email-masked]>
Date: Tue, 12 Feb 2013 21:52:03 +0000

Here's a slightly more useful link than the previous one!

http://tools.ietf.org/html/draft-kelly-json-hal-05

--
Mike

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123

---

From: Mike Kelly <[email-masked]>
Date: Wed, 13 Feb 2013 17:59:38 +0000

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

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?

Cheers,
M

On 13 Feb 2013 17:35, "Craig McClanahan" <[email-masked]> 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-masked]>
wrote:
>> On Tue, Feb 12, 2013 at 7:53 AM, Mike Kelly [email-masked]>
wrote:
>> __._,_.___
>> Reply via web post
>> Reply to sender
>> Reply to group
>> Start a New Topic
>> Messages in this topic (2)
>> Recent Activity:
>> New Members 5
>> Visit Your Group
>> Switch to: Text-Only, Daily Digest • Unsubscribe • Terms of Use • Send
us Feedback
>> .
>> __,_._,___

---

From: Craig McClanahan <[email-masked]>
Date: Wed, 13 Feb 2013 09:35:53 -0800

Craig McClanahan

On Tue, Feb 12, 2013 at 1:52 PM, Mike Kelly <[email-masked]> wrote:

> **
> On Tue, Feb 12, 2013 at 7:53 AM, Mike Kelly [email-masked]> wrote:
> > Hello all,
> >
>   Reply via web post<http://groups.yahoo.com/group/rest-discuss/post;_ylc=X3oDMTJxcjUxcHEwBF9TAzk3MzU5NzE0BGdycElkAzQzMTkyNTUEZ3Jwc3BJZAMxNzA1NzAxMDE0BG1zZ0lkAzE5MjY4BHNlYwNmdHIEc2xrA3JwbHkEc3RpbWUDMTM2MDcwNTkyNQ--?act=reply&messageNum=19268>  Reply
> to sender
> <[email-masked]?subject=Re%3A%20New%20Internet-Draft%3A%20JSON%20Hypertext%20Application%20Language>  Reply
> to group
> <[email-masked]?subject=Re%3A%20New%20Internet-Draft%3A%20JSON%20Hypertext%20Application%20Language>  Start
> a New Topic<http://groups.yahoo.com/group/rest-discuss/post;_ylc=X3oDMTJlbWZsMThpBF9TAzk3MzU5NzE0BGdycElkAzQzMTkyNTUEZ3Jwc3BJZAMxNzA1NzAxMDE0BHNlYwNmdHIEc2xrA250cGMEc3RpbWUDMTM2MDcwNTkyNQ-->  Messages
> in this topic<http://groups.yahoo.com/group/rest-discuss/message/19267;_ylc=X3oDMTM2OHNmZ3U1BF9TAzk3MzU5NzE0BGdycElkAzQzMTkyNTUEZ3Jwc3BJZAMxNzA1NzAxMDE0BG1zZ0lkAzE5MjY4BHNlYwNmdHIEc2xrA3Z0cGMEc3RpbWUDMTM2MDcwNTkyNQR0cGNJZAMxOTI2Nw-->(2)
> Recent Activity:
>
>    - New Members<http://groups.yahoo.com/group/rest-discuss/members;_ylc=X3oDMTJmMjR0MXNuBF9TAzk3MzU5NzE0BGdycElkAzQzMTkyNTUEZ3Jwc3BJZAMxNzA1NzAxMDE0BHNlYwN2dGwEc2xrA3ZtYnJzBHN0aW1lAzEzNjA3MDU5MjU-?o=6>
>    5
>
>  Visit Your Group<http://groups.yahoo.com/group/rest-discuss;_ylc=X3oDMTJlaDEydWZ1BF9TAzk3MzU5NzE0BGdycElkAzQzMTkyNTUEZ3Jwc3BJZAMxNzA1NzAxMDE0BHNlYwN2dGwEc2xrA3ZnaHAEc3RpbWUDMTM2MDcwNTkyNQ-->
>  <http://groups.yahoo.com/;_ylc=X3oDMTJkOG5yYnNjBF9TAzk3MzU5NzE0BGdycElkAzQzMTkyNTUEZ3Jwc3BJZAMxNzA1NzAxMDE0BHNlYwNmdHIEc2xrA2dmcARzdGltZQMxMzYwNzA1OTI1>
> Switch to: Text-Only<[email-masked]?subject=Change+Delivery+Format:+Traditional>,
> Daily Digest<[email-masked]?subject=Email+Delivery:+Digest>•
> Unsubscribe <[email-masked]?subject=Unsubscribe>• Terms
> of Use <http://docs.yahoo.com/info/terms/> • Send us Feedback
> <[email-masked]?subject=Feedback+on+the+redesigned+individual+mail+v1>
>    .
>
> __,_._,___
>

---

From: Craig McClanahan <[email-masked]>
Date: Wed, 13 Feb 2013 13:42:20 -0800

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