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

Re: [rest-discuss] How to approve?

Expand Messages
  • Jan Algermissen
    ... You need to define hypermedia semantics (a media type or link relation) that tell the user agent what request to initiate to achieve the desired result
    Message 1 of 5 , Jan 17, 2011
    • 0 Attachment
      On Jan 17, 2011, at 2:53 PM, Zhi-Qiang Lei wrote:

      > Dear All,
      >
      > In my application, there are a kind of ticket resources (URI: /tickets/{ticket-id}), and the ticket behaves like a state machine (status: pending -> approved or pending -> deny). Could you tell me what is a RESTful way to approve the tickets? Because there is no APPROVE manner in HTTP. Thanks in advance.
      >

      You need to define hypermedia semantics (a media type or link relation) that tell the user agent what request to initiate to achieve the desired result (approval).

      One way to do this would be through a dedicated ITSM-tailored media type [1]. Such a media type could define status values for a status property of resources (e.g. tickets). You could do sth like this:


      GET /tickets/56

      200 Ok
      Content-Type: application/itsm

      <ticket>
      <type="Incident">
      <status url="./status">pending</status>
      ....
      </ticket>

      You could then

      PUT /tickets/56/status
      Content-Type: text/plain

      approved

      Another possibility would be through a Link relation that tells you where the status property is:

      GET /tickets/56

      200 Ok
      Link: </tickets/56/status/>;rel=status
      Content-Type: application/itsm

      <ticket>...</ticket>

      You could then do

      PUT /tickets/56/status
      Content-Type: text/plain


      HTH,

      Jan







      [1] Would be a nice REST-show case, IMHO, because ITSM as a domain suits REST pretty well, I think.

      > Best regards,
      > Zhi-Qiang Lei
      > zhiqiang.lei@...
      >
      >
      >
      > ------------------------------------
      >
      > Yahoo! Groups Links
      >
      >
      >
    • mike amundsen
      Zhi-Qiang Lei: Sounds like you need to change the state of the ticket. You can do this using PUT to replace the current ticket state w/ the new ticket state.
      Message 2 of 5 , Jan 17, 2011
      • 0 Attachment
        Zhi-Qiang Lei:

        Sounds like you need to change the state of the ticket.

        You can do this using PUT to replace the current ticket state w/ the
        new ticket state.
        PUT /ticket/123 ("direct resource")
        ...
        ... ticket state ...

        Possible advantages: clients are dealing with the existing ticket and
        intermediaries will recognize the updated state of the ticket very
        easily.
        Possible disadvantages: if the ticket state is large, you must pass
        quite a bit of data to simply "approve" the ticket.

        You can do this using POST to add a new ticket-status which will
        update the ticket state
        POST /ticket/123/status ("sub-resource")
        OR
        POST /ticket/status?ticket=123 ("controller resource")
        ...
        ... "approved" ...
        Possible advantages: clients pass only the data that is changed and
        you get an easy "audit trail" of all state changes that can be
        retrieved, replayed, etc.
        Possible disadvantages: this is an indirect way to affect the ticket
        resource that intermediaries will not easy understand.

        These are the first two possibilities that come to mind. There may be others.

        mca
        http://amundsen.com/blog/
        http://twitter.com@mamund
        http://mamund.com/foaf.rdf#me


        #RESTFest 2010
        http://rest-fest.googlecode.com




        On Mon, Jan 17, 2011 at 08:53, Zhi-Qiang Lei <zhiqiang.lei@...> wrote:
        > Dear All,
        >
        > In my application, there are a kind of ticket resources (URI: /tickets/{ticket-id}), and the ticket behaves like a state machine (status: pending -> approved or pending -> deny). Could you tell me what is a RESTful way to approve the tickets? Because there is no APPROVE manner in HTTP. Thanks in advance.
        >
        > Best regards,
        > Zhi-Qiang Lei
        > zhiqiang.lei@...
        >
        >
        >
        > ------------------------------------
        >
        > Yahoo! Groups Links
        >
        >
        >
        >
      • Erik Mogensen
        ... I guess this will be heavily debated, but in a strictly RESTful interface, the client should discover the available options (state transitions). So if
        Message 3 of 5 , Jan 17, 2011
        • 0 Attachment
          On Mon, Jan 17, 2011 at 2:53 PM, Zhi-Qiang Lei <zhiqiang.lei@...> wrote:
          In my application, there are a kind of ticket resources (URI: /tickets/{ticket-id}), and the ticket behaves like a state machine (status: pending -> approved or pending -> deny). Could you tell me what is a RESTful way to approve the tickets? Because there is no APPROVE manner in HTTP. Thanks in advance.

          I guess this will be heavily debated, but in a strictly RESTful interface, the client should discover the available options (state transitions).  So if your media type is HTML, your initial GET request might be

          GET /tickets/1234
          200 OK
          <form method="post">
            <input type="hidden" name="approve" value="true">
            Click this button to approve this ticket <input type="submit">
          </form>

          (not the prettiest UI but it gets the point across.)

          Using the above HTML page, the client will provide enough information to the user what happens when he clicks the button, and clicking the button will result in a HTTP POST to /ticket/1234 with "approve=true" in the body.  The response could be a redirect back to /ticket/1234 which would show the updated resource state.

          The client just transitioned the state of the ticket without knowing what that ticket states are.

          If your server has more specific media types than HTML, e.g. application/x-ticket or whatever, then the definition of application/x-ticket would typically provide similar documentation indicating that "the presence of <link rel=approve href=.../> indicates that the client should POST something to that href to approve the ticket."  This would require the knowledge of application/x-ticket and its processing requirements.

          Atom does this, e.g. for <link rel="edit"> clients are expected to GET and PUT to modify items.  <app:collection> defines that the URI allows POST, which creates a new entry in the referenced collection.

          HTML defines <form action=xxx method=post> to instruct clients to perform HTTP POST.

          The primary example of this would probably be the sun cloud API where the media types instruct to POST specific JSON structures to discovered URIs in order to perform quite high level operations (like turning on a machine). <http://kenai.com/projects/suncloudapis/pages/Home>
          -- 
          -mogsie-
        • Zhi-Qiang Lei
          Thanks. Your PUT example inspires me much. I always thought that representation should be key-value pairs. ... Best regards, Zhi-Qiang Lei
          Message 4 of 5 , Jan 17, 2011
          • 0 Attachment
            Thanks. Your PUT example inspires me much. I always thought that representation should be key-value pairs.

            On Jan 17, 2011, at 10:40 PM, Jan Algermissen wrote:

             


            On Jan 17, 2011, at 2:53 PM, Zhi-Qiang Lei wrote:

            > Dear All,
            >
            > In my application, there are a kind of ticket resources (URI: /tickets/{ticket-id}), and the ticket behaves like a state machine (status: pending -> approved or pending -> deny). Could you tell me what is a RESTful way to approve the tickets? Because there is no APPROVE manner in HTTP. Thanks in advance.
            >

            You need to define hypermedia semantics (a media type or link relation) that tell the user agent what request to initiate to achieve the desired result (approval).

            One way to do this would be through a dedicated ITSM-tailored media type [1]. Such a media type could define status values for a status property of resources (e.g. tickets). You could do sth like this:

            GET /tickets/56

            200 Ok
            Content-Type: application/itsm

            <ticket>
            <type="Incident">
            <status url="./status">pending</status>
            ....
            </ticket>

            You could then

            PUT /tickets/56/status
            Content-Type: text/plain

            approved

            Another possibility would be through a Link relation that tells you where the status property is:

            GET /tickets/56

            200 Ok
            Link: </tickets/56/status/>;rel=status
            Content-Type: application/itsm

            <ticket>...</ticket>

            You could then do

            PUT /tickets/56/status
            Content-Type: text/plain

            HTH,

            Jan

            [1] Would be a nice REST-show case, IMHO, because ITSM as a domain suits REST pretty well, I think.

            > Best regards,
            > Zhi-Qiang Lei
            > zhiqiang.lei@...
            >
            >
            >
            > ------------------------------------
            >
            > Yahoo! Groups Links
            >
            >
            >



            Best regards,
            Zhi-Qiang Lei

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