Loading ...
Sorry, an error occurred while loading the content.

Re: [rest-discuss] Re: New Internet-Draft: JSON Hypertext Application Language

Expand Messages
  • Craig McClanahan
    ... Well, my task was to define public HTTP APIs for our resources, so binding to HTTP semantics didn t really bother me :-). ... I think there are (at least)
    Message 1 of 5 , Feb 13, 2013
      On Wed, Feb 13, 2013 at 9:59 AM, Mike Kelly <mikekelly321@...> 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"?




      On 13 Feb 2013 17:35, "Craig McClanahan" <craigmcc@...> 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 <mikekelly321@...> 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 mikekelly321@...> 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

    Your message has been successfully submitted and would be delivered to recipients shortly.