On Nov 18, 2012, at 4:49 AM, Max Toro <maxtoroq@...> wrote:

> Found this statement on the web:
> "Implementing a http://www.mysite.com/invoice/add URI is not
> considered a REST compliant practice."
>
> What do you guys think?

What the quote is trying to say is, I guess, that designing interactions in the
spirit of RPC (here: InvoceService.add(invoice)) is not RESTful.

'Correct' would be sth like

POST /invoices

Content-type: application/foo.invoice

<invoice> ... </invoice>

You do not need an 'add' semantic.


As for the URI string per se: that is opaque and meaningless (as Erik and Steve
already noted).

Jan





> --
> Max Toro
>

On Thu, Nov 29, 2012 at 12:26:00PM +0100, Erlend Hamnaberg wrote:

> Is there anyone with experiences with implementing API Keys in their apis?
>
> Putting the APIKey in the URI is obviously a bad idea as that leaks to every
> cache and intermediary. Including Apache logs.
>
> So it must be a new header field.

The WWW-Authenticate and Authorization headers exist for this very
purpose. In fact, RFC 2617 is designed to be extensible.

> The problem with APIKeys as such is that they are spoofable, unless they are
> crypographically protected somehow, so my question is:
>
> What do you do in your api?

HTTP auth headers. There's really no need for anything else except maybe
in cases where it's not possible to use HTTP auth (such as embedding a
fragment of JavaScript in a page, such as with Google Analytics, in
which case you're not going to care much about spoofability anyway). For
all other cases, using the existing HTTP auth headers is the right way
to go because you *are* performing a form of auth with an API key.

> ps:
> I am thinking about writing up an internet draft for a new Api-Key header
> field.

You'd be better off proposing an alternative HTTP auth method, if
anything, where the client sends something like this (assuming the API
key is a UUID):

     Authorization: Key b67570be-3a22-11e2-8ca6-0015c55d83ee

Of course, that assumes a fixed key. If you wanted something more secure
and less liable to be spoofed, you'd end up with something similar to
Digest auth, so you might want to consider just using that unless you
can come up with something provably superior. Here's an example of an
alternative auth method:

     http://www.xml.com/pub/a/2003/12/17/dive.html

K.

--
Cíat Ó Gáibhtheacháin - k@... - http://stereochro.me/ - CF9F6473
True happiness comes from the joy of deeds well done,
                           the zest of creating things new.
     -- Antoine de Saint-Exupery

On Thu, Nov 29, 2012 at 02:16:50PM +0100, Erlend Hamnaberg wrote:

> This seems to indicate that a User and Acces to the API is the same.
> It is not in this case.

This isn't the case, otherwise the likes of OAuth (which I mention
later) wouldn't be possible.

> Using Authorization was considered, but we need to use this for user
> authentication. API authorization is a different step.
>
> AFAIK you MAY NOT send multiple challenges back to the server.

I think you might be missing the greater point I was trying to make,
which were that an existing mechanism already exist (RFC 2617):

>     The WWW-Authenticate and Authorization headers exist for this very
>     purpose. In fact, RFC 2617 is designed to be extensible.

In fact, is this very extensibility that OAuth is built upon. OAuth
might not be ideal for your particular purpose, but RFC 2617 still
exists to build upon to quite possibly do what you want.

It's possible to build an RFC 2617 auth method that could potentially
bundle multiple challenges in a single aggregate challenge. Including
multiple 'WWW-Authenticate' and 'Authorization' headers is another
matter, however.

Without knowing more about how your system's access management
requirements, it's hard to speculate further. I think it would be more
valuable to propose an auth method built on top of RFC 2617 to support
your requirements rather than a whole new header.

--
Cíat Ó Gáibhtheacháin - k@... - http://stereochro.me/ - CF9F6473
There are 10^11 stars in the galaxy. That used to be a huge number. But it's
only a hundred billion. It's less than the national deficit! We used to call
them astronomical numbers. Now we should call them economical numbers.
     -- Richard Feynman

Hi Erlend,

On Nov 29, 2012, at 12:26 PM, Erlend Hamnaberg <ngarthl@...> wrote:

> Hi.
>
>
> Is there anyone with experiences with implementing API Keys in their apis?

If you are looking for something along the lines of OAuth Client identifiers,
you should take a look at OAuth 1 and 2 and the associated discussions.

Eran IMO is the go-to guy in that space and you should get much out of his blog

http://hueniverse.com

and recent projects

https://github.com/hueniverse/oz

https://github.com/hueniverse/hawk (The README should provide a very good
start).

Looking at Amazon IAM, as already suggested, is also good:

http://aws.amazon.com/documentation/iam/

Here are good intro docs from Google:

https://developers.google.com/accounts/docs/OAuth2

Personally, I am most excited about OZ, because Eran's OAuth 2 criticism looks
very valid when you dig into it.


HTH
Jan


>
> Putting the APIKey in the URI is obviously a bad idea as that leaks to every
cache and intermediary. Including Apache logs.
>
> So it must be a new header field.
>
> The problem with APIKeys as such is that they are spoofable, unless they are
crypographically protected somehow, so my question is:
>
> What do you do in your api?
>
>
> --
> Erlend
>
>
> ps:
> I am thinking about writing up an internet draft for a new Api-Key header
field.
>
>

On Thu, Nov 29, 2012 at 5:55 AM, Cíat Ó Gáibhtheacháin <k@...> wrote:
> You'd be better off proposing an alternative HTTP auth method, if
> anything, where the client sends something like this (assuming the API
> key is a UUID):
>
>     Authorization: Key b67570be-3a22-11e2-8ca6-0015c55d83ee

+1, HTTP auth is a tragically underused part of the standard.

Peter
barelyenough.org

you'd end up with something similar to
Digest auth, so you might want to consider just using that unless you
can come up with something provably superior. Here's an example of an
alternative auth method:

   http://www.xml.com/pub/a/2003/12/17/dive.html

Thanks for your answers, it's pretty much what I had in mind.

I want to discuss a second example:

a)
POST /orders/1/cancel

vs.

b)
PATCH /orders/1

canceled=true


Does REST say anything in favor or against these two designs?

Personally, I would never do 'b' because it's simply hard to implement
with the tools I use. Also, isn't it a case of tunneling? 'Cancel' is
an action that does more than simply update a resource.

--
Max Toro

On 30 Nov 2012, at 13:15, Max Toro wrote:

> Thanks for your answers, it's pretty much what I had in mind.
>
> I want to discuss a second example:
>
> a)
> POST /orders/1/cancel
>
> vs.
>
> b)
> PATCH /orders/1
>
> canceled=true
>
>
> Does REST say anything in favor or against these two designs?

REST says "Do 'b', never 'a'." Sorry!
The simple rule is URIs are for nouns, HTTP methods are for verbs.

You could get away with this though:

POST /orders/1
cancelled=true

Originally, POST was intended to mean "post a reply" the same as it's NNTP
namesake/predecessor. Now, though, the authors of HTTP concede that it's modern
meaning is "Hey, server, use these data (request body) to perform some action to
this resource (uri)"

As such, by POSTing to /orders/1 you are at least getting the resource part of
the API right, even if you are lacking the semantics of a PATCH request.

> Personally, I would never do 'b' because it's simply hard to implement
> with the tools I use. Also, isn't it a case of tunneling? 'Cancel' is
> an action that does more than simply update a resource.


I wouldn't call it tunnelling, tunnelling would be something like:

POST /orders/1

_method_override="DELETE"    // could also be custom HTTP header

If the "cancel" action is just updating a resource state, rather then, say,
DELETEing the resource, then you could even do something like:

PUT /orders/1/cancelled
true

(again, use POST if you can't PUT)

and correspondingly:

GET /orders/1/cancelled

=> "true"

GET /orders/2/cancelled

=> "false"

(or 1/0, yes/no, … however you wish to represent it)


For reference, stackoverflow.com is a good place to go with these sorts of
questions. Many have already been asked in various forms, you'll find the
answers already provided.

— Nicholas.

On Nov 30, 2012, at 7:08 PM, Nicholas Shanks <nickshanks@...> wrote:

> On 30 Nov 2012, at 13:15, Max Toro wrote:
>
>> Thanks for your answers, it's pretty much what I had in mind.
>>
>> I want to discuss a second example:
>>
>> a)
>> POST /orders/1/cancel
>>
>> vs.
>>
>> b)
>> PATCH /orders/1
>>
>> canceled=true
>>
>>
>> Does REST say anything in favor or against these two designs?
>
> REST says "Do 'b', never 'a'." Sorry!

Yes, right.

If it suits your use cases, consider:

DELETE /orders/1

Which might well result in the order being moved to a cancled-orders collection.
IOW, it need not be erased entirely.

Jan





> The simple rule is URIs are for nouns, HTTP methods are for verbs.
>
> You could get away with this though:
>
> POST /orders/1
> cancelled=true
>
> Originally, POST was intended to mean "post a reply" the same as it's NNTP
namesake/predecessor. Now, though, the authors of HTTP concede that it's modern
meaning is "Hey, server, use these data (request body) to perform some action to
this resource (uri)"
>
> As such, by POSTing to /orders/1 you are at least getting the resource part of
the API right, even if you are lacking the semantics of a PATCH request.
>
>> Personally, I would never do 'b' because it's simply hard to implement
>> with the tools I use. Also, isn't it a case of tunneling? 'Cancel' is
>> an action that does more than simply update a resource.
>
>
> I wouldn't call it tunnelling, tunnelling would be something like:
>
> POST /orders/1
>
> _method_override="DELETE"    // could also be custom HTTP header
>
> If the "cancel" action is just updating a resource state, rather then, say,
DELETEing the resource, then you could even do something like:
>
> PUT /orders/1/cancelled
> true
>
> (again, use POST if you can't PUT)
>
> and correspondingly:
>
> GET /orders/1/cancelled
>
> => "true"
>
> GET /orders/2/cancelled
>
> => "false"
>
> (or 1/0, yes/no, … however you wish to represent it)
>
>
> For reference, stackoverflow.com is a good place to go with these sorts of
questions. Many have already been asked in various forms, you'll find the
answers already provided.
>
> — Nicholas.
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

+1 on this, it probably would be a good mapping of domain interactions
to HTTP verbs.

On 2012-11-30 10:43 , Jan Algermissen wrote:
>
> On Nov 30, 2012, at 7:08 PM, Nicholas Shanks <nickshanks@...>
wrote:
>
>> On 30 Nov 2012, at 13:15, Max Toro wrote:
>>
>>> Thanks for your answers, it's pretty much what I had in mind.
>>>
>>> I want to discuss a second example:
>>>
>>> a)
>>> POST /orders/1/cancel
>>>
>>> vs.
>>>
>>> b)
>>> PATCH /orders/1
>>>
>>> canceled=true
>>>
>>>
>>> Does REST say anything in favor or against these two designs?
>>
>> REST says "Do 'b', never 'a'." Sorry!
>
> Yes, right.
>
> If it suits your use cases, consider:
>
> DELETE /orders/1
>
> Which might well result in the order being moved to a cancled-orders
collection. IOW, it need not be erased entirely.
>
> Jan
>
>
>
>
>
>> The simple rule is URIs are for nouns, HTTP methods are for verbs.
>>
>> You could get away with this though:
>>
>> POST /orders/1
>> cancelled=true
>>
>> Originally, POST was intended to mean "post a reply" the same as it's NNTP
namesake/predecessor. Now, though, the authors of HTTP concede that it's modern
meaning is "Hey, server, use these data (request body) to perform some action to
this resource (uri)"
>>
>> As such, by POSTing to /orders/1 you are at least getting the resource part
of the API right, even if you are lacking the semantics of a PATCH request.
>>
>>> Personally, I would never do 'b' because it's simply hard to implement
>>> with the tools I use. Also, isn't it a case of tunneling? 'Cancel' is
>>> an action that does more than simply update a resource.
>>
>>
>> I wouldn't call it tunnelling, tunnelling would be something like:
>>
>> POST /orders/1
>>
>> _method_override="DELETE"    // could also be custom HTTP header
>>
>> If the "cancel" action is just updating a resource state, rather then, say,
DELETEing the resource, then you could even do something like:
>>
>> PUT /orders/1/cancelled
>> true
>>
>> (again, use POST if you can't PUT)
>>
>> and correspondingly:
>>
>> GET /orders/1/cancelled
>>
>> => "true"
>>
>> GET /orders/2/cancelled
>>
>> => "false"
>>
>> (or 1/0, yes/no, … however you wish to represent it)
>>
>>
>> For reference, stackoverflow.com is a good place to go with these sorts of
questions. Many have already been asked in various forms, you'll find the
answers already provided.
>>
>> — Nicholas.
>>
>>
>> ------------------------------------
>>
>> Yahoo! Groups Links
>>
>>
>>
>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

--
erik wilde | mailto:dret@...  -  tel:+1-510-2061079 |
             | UC Berkeley  -  School of Information (ISchool) |
             | http://dret.net/netdret http://twitter.com/dret |

+1 to the other answers you've gotten.  Except...

REST is about optimizing the hell out of GET.  The hypertext containing
the PUT control is one place to GET the order status.  But, why cache-
expire the entire record when only one string is changed, multiple times
after the order is placed and becomes static?  A RESTful order-status
API should separate the dynamic aspects of order processing from the
static, as sub-resources, and manipulate *those* to alter a dynamic
representation of the static order.  This becomes especially efficient
when, say, a CC is rejected and the customer needs to enter another one.

Consider PUT /orders/1/status with strings like placed, processing,
pending, and the tracking # from the shipper -- I'd even consider
application/xml and application/json acceptable media types for a
snippet like this, of course not for the hypertext control defining the
PUT.  I'd never PUT 'canceled', I'd use DELETE as Jan described, which
would trigger a reshelving-fee transaction, with /status returning
reshelving on 200 OK, before /orders/1* return 410 Gone, indicating the
transaction has been fully reversed including by the inventory system.

Using code-on-demand to fill in the current status on the PUT control
exposes a status API which may be utilized many different ways (push,
poll, etc.), allowing for serendipitous re-use.  The downside of being
an additional round-trip is mitigated by using compression such that the
/status 200 OK response fits in one IP packet.  Note that XForms may be
used to make this code declarative, avoiding the optional constraint.

This thread isn't about URI design at all, in fact it's irrelevant to
this discussion about hypertext-driven application state, as is method
selection. Also RESTful: /CRMapp?order=1&query=status on GET, and
/CRMapp?order=1&status=canceled on POST using application/x-www-form-
urlencoded, if we assume the hypertext constraint is met, which is what
this thread is really about.

Then we can discuss the pros and cons of various media types which can
implement a RESTful status API, regardless of how the shopping cart is
implemented.  If you're working with making a legacy system more
RESTful over time, you may want HTML 4, JS and POST.  If this is
greenfield, you may consider XForms w/ PUT and DELETE.  Or, use HTML 5
if this is a Web system, not sure where it is regarding PUT/DELETE, but
it really doesn't matter...

The key is the architectural consideration of using subresources for
dynamic elements like order status, allowing the order itself to become
sticky in the client-side cache, while also allowing manipulation of
that resource to occur in one-IP-packet round-trips.  Optimizing
PUT/POST/PATCH doesn't amount to much in the grand scheme of things,
what counts is optimizing GET by making static all those bytes which
make up the order being processed, and manipulating its subresources.

The hypertext interface doesn't even have to reflect the strings
in /status, it could be a graphical progress bar followed by e-mailing
the tracking number (instead of, or in addition to, displaying it).  Or,
the strings in /status 200 OK could be numerals, whose semantics are
conveyed by the PUT control or other hypertext conveying order status.

Always remember REST is an architectural style, not implementation
guidelines.  If you take one thing from it, it should be "optimize GET
to maximize caching."  Then, any implementation mistakes you make are
correctable down the line, instead of coming here and being told to go
back to the drawing board -- iow, if you've separated static from
dynamic as an architectural pattern, then we can make changes to URIs
and methods based on what media types are most appropriate for your
application, because that'll be bikeshedding if you get your resources
right.

I prefer developing REST systems in XForms, makes it easy to separate
static from dynamic in declarative code, to get a handle on what your
resources *are* and how they relate to one another.  I call this
hypertext-constraint-centric development.  The result is a hypertext API
which may then be implemented any way it needs to be, letting the
implementation requirements dictate the system's ultimate hypertext, URI
allocation scheme, and media types if (most likely) XForms isn't
appropriate.  I may hate my HTML 4 implementations' URIs and methods,
but the underlying systems are implicitly RESTful and thus easy to
upgrade over time, as new hypertext technology emerges and matures.

-Eric

On Fri, 30 Nov 2012 10:45:26 -0800
Erik Wilde <dret@...> wrote:

> +1 on this, it probably would be a good mapping of domain
> interactions to HTTP verbs.
>
> On 2012-11-30 10:43 , Jan Algermissen wrote:
> >
> > On Nov 30, 2012, at 7:08 PM, Nicholas Shanks
> > <nickshanks@...> wrote:
> >
> >> On 30 Nov 2012, at 13:15, Max Toro wrote:
> >>
> >>> Thanks for your answers, it's pretty much what I had in mind.
> >>>
> >>> I want to discuss a second example:
> >>>
> >>> a)
> >>> POST /orders/1/cancel
> >>>
> >>> vs.
> >>>
> >>> b)
> >>> PATCH /orders/1
> >>>
> >>> canceled=true
> >>>
> >>>
> >>> Does REST say anything in favor or against these two designs?
> >>
> >> REST says "Do 'b', never 'a'." Sorry!
> >
> > Yes, right.
> >
> > If it suits your use cases, consider:
> >
> > DELETE /orders/1
> >
> > Which might well result in the order being moved to a
> > cancled-orders collection. IOW, it need not be erased entirely.
> >
> > Jan
> >
> >
> >
> >
> >
> >> The simple rule is URIs are for nouns, HTTP methods are for verbs.
> >>
> >> You could get away with this though:
> >>
> >> POST /orders/1
> >> cancelled=true
> >>
> >> Originally, POST was intended to mean "post a reply" the same as
> >> it's NNTP namesake/predecessor. Now, though, the authors of HTTP
> >> concede that it's modern meaning is "Hey, server, use these data
> >> (request body) to perform some action to this resource (uri)"
> >>
> >> As such, by POSTing to /orders/1 you are at least getting the
> >> resource part of the API right, even if you are lacking the
> >> semantics of a PATCH request.
> >>
> >>> Personally, I would never do 'b' because it's simply hard to
> >>> implement with the tools I use. Also, isn't it a case of
> >>> tunneling? 'Cancel' is an action that does more than simply
> >>> update a resource.
> >>
> >>
> >> I wouldn't call it tunnelling, tunnelling would be something like:
> >>
> >> POST /orders/1
> >>
> >> _method_override="DELETE"    // could also be custom HTTP header
> >>
> >> If the "cancel" action is just updating a resource state, rather
> >> then, say, DELETEing the resource, then you could even do
> >> something like:
> >>
> >> PUT /orders/1/cancelled
> >> true
> >>
> >> (again, use POST if you can't PUT)
> >>
> >> and correspondingly:
> >>
> >> GET /orders/1/cancelled
> >>
> >> => "true"
> >>
> >> GET /orders/2/cancelled
> >>
> >> => "false"
> >>
> >> (or 1/0, yes/no, … however you wish to represent it)
> >>
> >>
> >> For reference, stackoverflow.com is a good place to go with these
> >> sorts of questions. Many have already been asked in various forms,
> >> you'll find the answers already provided.
> >>
> >> — Nicholas.
> >>
> >>
> >> ------------------------------------
> >>
> >> Yahoo! Groups Links
> >>
> >>
> >>
> >
> >
> >
> > ------------------------------------
> >
> > Yahoo! Groups Links
> >
> >
> >
>
> --
> erik wilde | mailto:dret@...  -  tel:+1-510-2061079 |
>             | UC Berkeley  -  School of Information (ISchool) |
>             | http://dret.net/netdret http://twitter.com/dret |

Nicholas Shanks wrote:
>
> For reference, stackoverflow.com is a good place to go with these
> sorts of questions. Many have already been asked in various forms,
> you'll find the answers already provided.
>

Pretty good answer, except for that...  Welcome to rest-discuss!  ;-)

Here, the archives are full of list regulars being told directly by the
likes of Roy and Mark dozens of times that we're wrong.  Gradually,
this group has become _the_ place to get schooled on REST as intended
by Fielding.  There, I don't see many answers from those who've put
their knowledge to the test, here.  What I do see are attempts to define
REST in terms of implementation rather than style, i.e. Wikipedia REST,
not Fielding REST.

So pick the place that best suits your needs -- there if you want
implementation, here if you want architecture; there is a difference,
which comes down to the proportion of answers from those who've been
"vetted" by Roy (and Mark, and others) over the years, and understand
REST as an architectural style as opposed to implementation guidelines.

Just my two cents.

-Eric

The downside of being
an additional round-trip is mitigated by using compression such that the
/status 200 OK response fits in one IP packet. 

What I'd love to get is an answer like: POST /orders/1/cancel is not
REST compliant because chapter x of Fielding's dissertation explicitly
or implicitly says it's not allowed or it's discouraged. After knowing
what is or isn't REST then I'd love to learn more about the pros and
cons of different architectural and implementation styles.
--
Max Toro


On Fri, Nov 30, 2012 at 6:12 PM, Eric J. Bowman <eric@...> wrote:
> Nicholas Shanks wrote:
>>
>> For reference, stackoverflow.com is a good place to go with these
>> sorts of questions. Many have already been asked in various forms,
>> you'll find the answers already provided.
>>
>
> Pretty good answer, except for that...  Welcome to rest-discuss!  ;-)
>
> Here, the archives are full of list regulars being told directly by the
> likes of Roy and Mark dozens of times that we're wrong.  Gradually,
> this group has become _the_ place to get schooled on REST as intended
> by Fielding.  There, I don't see many answers from those who've put
> their knowledge to the test, here.  What I do see are attempts to define
> REST in terms of implementation rather than style, i.e. Wikipedia REST,
> not Fielding REST.
>
> So pick the place that best suits your needs -- there if you want
> implementation, here if you want architecture; there is a difference,
> which comes down to the proportion of answers from those who've been
> "vetted" by Roy (and Mark, and others) over the years, and understand
> REST as an architectural style as opposed to implementation guidelines.
>
> Just my two cents.
>
> -Eric

Will Hartung wrote:
>
> >
> > The downside of being
> > an additional round-trip is mitigated by using compression such
> > that the /status 200 OK response fits in one IP packet.
> >
> Unless your in a mobile environment where latency mutders you and
> compression is a secondary benefit.
>

Right, YMMV with compression, but the main point is that the bulk of
the order is static data and therefore may be made highly persistent in
the client cache (cache-control: private), _that_ is how both round
trips and the transfer of a significant amount of bytes may be avoided,
even without optionally compressing certain traffic into one IP packet.
Architecture vs. implementation.  That being said...

I don't understand why compression is bad for latency, though.  I cache
compressed data, and unzip it on the fly, so the expensive zip operation
is only done once by the server each time the resource is updated. Which
means the only user who experiences zip latency, is the user who updates
the resource -- but does another second (if that) get perceived by the
user on PUT/POST/PATCH operations, and is there any real benefit to
optimizing these operations when GET is only like a billion times more
common a request method?  I think not.

Are mobile clients still so underpowered that their zip/unzip latency
exceeds the transfer gains?  Especially if we're talking about
manipulating resources and updating representations using one single-
packet-each-way round trip, double especially if we're talking about
users who are, you know, *mobile*.  If the client is moving from one
access point to another, caching the bulk of the data on the client and
using single-packet messaging is guaranteed to avoid the huge latency
hit of changing IP address/routing while manipulating a resource, which
seems to me like a huge gain in user-perceived performance.

-Eric

Technically, of course, I mean "high probability of being a single
packet" when arbitrarily small messages (including headers) have their
payload compressed.  This also depends on protocol -- HTTP 2 will allow
larger payloads to be compressed to one packet by slimming down header
size compared to HTTP 1.1, for example.

-Eric

Max Toro wrote:
>
> What I'd love to get is an answer like: POST /orders/1/cancel is not
> REST compliant because chapter x of Fielding's dissertation explicitly
> or implicitly says it's not allowed or it's discouraged. After knowing
> what is or isn't REST then I'd love to learn more about the pros and
> cons of different architectural and implementation styles.
>

Well, what are you expecting to GET from /cancel, or are you just using
that URL to invoke a procedure? If so, then there are a few places Roy's
thesis admonishes against it in Chapter 6 -- the rest of REST is about
positive, rather than negative, reinforcement of the identification of
resources constraint. Suggested reading: 6.5.2; 6.2.1, in particular:
"REST [defines] a resource to be the semantics of what the author
intends to identify."

Not the semantics of a method invocation.  What does /cancel identify?
Sounds to me like a method of tunneling DELETE through POST which
identifies nothing, iow a procedure endpoint, which is characteristic
of various styles but not of the REST style.  The hypertext constraint
only makes sense if your resources make sense, in that their URLs are
identifiers rather than endpoints.

Roy's thesis really must be considered in its entirety, to understand
the uniform interface constraint (of which identification of resources
is a sub-constraint).  Chapter 1 introduces the notion of applying
design-by-constraint to networked software architecture, as inspired
by Eames IIRC.  "A style is a named set of constraints on architectural
elements that induces the set of properties desired of the
architecture." (4.3)

Chapter 2 defines terminology associated with networked software
architecture, which is required for understanding Chapter 3, which lays
out a methodology for evaluating various styles and applies this to
several examples.  Most importantly, Chapter 3 identifies the
constraints associated with various styles, and describes the properties
they induce in a system (which may or may not be beneficial or
detrimental to the system you're designing; remember there is no best
architecture, only that which is best for your system).  Which is of
course required for understanding Chapter 4.

Chapter 4 considers the problems raised by the WWW, and suggests that
the architecture may be improved by applying design-by-constraint to it,
in order to address those problems.  First, by identifying the desirable
properties of the early Web, and the constraints responsible for them;
next, by extending that architecture by adding additional constraints,
resulting in a new hybrid style consisting of aspects of existing
styles. Of course, this is required for understanding Chapter 5.

"REST provides a set of architectural constraints that, WHEN APPLIED
AS A WHOLE, emphasizes scalability of component interactions, generality
of interfaces, independent deployment of components, and intermediary
components to reduce interaction latency, enforce security, and
encapsulate legacy systems." (4.4)

Which brings us to Chapter 5, and the short answer to your question:
"POSTing to /cancel violates the Identification of Resources constraint,
and is therefore unRESTful."  But I've found that just giving that
answer tends to upset folks who've only read Chapter 5, then they get
defensive about why can't they call their API RESTful, accusations of
pedantry follow, and threads devolve into general ugliness, heheh...

My point is, you'll have a much harder time trying to understand REST
by being told bluntly what is and isn't RESTful, than you will by
reading Roy's thesis in its entirety.  As computer science dissertations
go, Roy produced a functional work of art, much as an Eames chair isn't
just a piece of furniture.  Understanding what the constraints are, and
where they come from, is vital to understanding how they're applied to
the Web to derive REST, and why they must be implemented as a whole to
achieve REST.

Only then will it become apparent when they're being violated, as in
the example given of POSTing to an unGETtable /cancel URL.  That level
of understanding comes from the bottom up, not from the top down, IMO.
Knowing what is or isn't REST depends on understanding the pros and
cons of various architectural styles, because that's what constraints
are, and constraints must be understood before their application to the
Web as REST can be understood.

More importantly, understanding REST as a style makes one a better
architect, because sometimes it's advantageous to deviate from REST's
constraints.  Which is why I'm always on about how saying something
isn't REST is not a value judgment, just a fact.  Understanding Roy's
thesis allows you to identify the constraints you have applied, and
understand that as its own architectural style derived from REST, to
use as a guide to developing that system -- but also to understand
which desirable properties of REST you're forfeiting in the bargain.

Making informed decisions about which constraints to apply, is making
use of REST as a tool for long-term development.  It may not be
feasible to apply all the constraints initially, if REST is truly what
your system needs.  In which case your system design can account for
this, becoming more RESTful over time, instead of painting yourself
into a corner where the system needs re-architecting rather than
implementing another constraint as an extension.

-Eric

"Eric J. Bowman" wrote:
>
> Making informed decisions about which constraints to apply, is making
> use of REST as a tool for long-term development.  It may not be
> feasible to apply all the constraints initially, if REST is truly what
> your system needs.  In which case your system design can account for
> this, becoming more RESTful over time, instead of painting yourself
> into a corner where the system needs re-architecting rather than
> implementing another constraint as an extension.
>

This is why Roy's thesis is an invaluable tool, at least for me anyway
as I've been at this since '93 and had a front-row seat at the
transition from the old Web to HTTP 1.1 -- Roy's experience applying
his concepts to a system I was familiar with is included in his thesis,
which helped me to incrementally apply REST to my own work as I gained
understanding of it.  Now, I can confidently design systems today which
may be easily extended to be fully RESTful tomorrow.

So I really don't stress about the unRESTful aspects of my systems,
they're "by design" and will continue to work themselves out over time.
Which is exactly what you want from an architectural style, particularly
for the Web.  Successful websites tend to grow users over time, and it
ain't easy to chuck one system for another.  What's needed is a system
which uses progressively less resources per user, as usage increases.

(Just check out the shoddy uptime records of certain big boys on the
block to see how badly this desirable property is needed, and note that
they don't begin to implement REST.)

Using REST as a tool enables the development of such systems by allowing
the architect to chart a steady course, deciding which constraints (like
identification of resources) are crucial to get right from the get-go,
and which may be put off until they satisfy a cost-benefit analysis.

For example, most popular CMS software defaults to no-cache.  But this
doesn't really matter until you're starting to bump into the transfer
limits of your hosting plan, at which time you can implement caching,
after having some time to test the setup first. You can then fine-tune
your cache settings over time, and later integrate with a CDN.  This is
usually done ad-hoc, what I'm saying is that knowledge of REST can make
this go smoothly rather than being a comedy of errors (quite common).

If your system doesn't grow to need it, then you can probably do without
all the added development expense (plus complexity driving up long-term
maintenance costs) of implementing non-native caching on that CMS. REST
is your friend when it comes to planning for and managing these expenses
and complexities vis-a-vis your cashflow.  Budgeting for ho-hum websites
is easy; successful websites are another story entirely, where knowledge
of REST as a tool can be your competitive edge in funding growth from
cashflow instead of debt or outside capital while turning a profit --
instead of piling up red ink on wasteful infrastructure.

Yeah, I know.  That just isn't how things are done on the Web!  :-D

-Eric

Greg Young wrote:
>
>  /CRMapp?order=1&query=status
>
> until intermediaries decide to ignore you because the ?
>
> :(
>
> They shouldn't but they do :)
>

They're configurable, and while this may have been a problem in the
past, I don't believe it to be anything but an edge case, now.  URIs
are opaque and should be considered in their entirety as cache keys.
The best a developer can do, is design to REST -- my example certainly
doesn't violate any constraints -- and let the deployed architecture
catch up.

There's much FUD out there about query strings, particularly in REST
discussions, which amounts to unfounded myth.  I see no reason to avoid
query strings because they *might* be ignored by a small percentage of
caches, economy of scale still kicks in vs. no-cache.  So go ahead and
treat URIs as opaque when doing REST development, the downside is
more than compensated for by the upside, more so as time goes by.

-Eric

> Well, what are you expecting to GET from /cancel, or are you just using
> that URL to invoke a procedure? If so, then there are a few places Roy's
> thesis admonishes against it in Chapter 6 -- the rest of REST is about
> positive, rather than negative, reinforcement of the identification of
> resources constraint. Suggested reading: 6.5.2; 6.2.1, in particular:
> "REST [defines] a resource to be the semantics of what the author
> intends to identify."

To clarify, /orders/1/cancel is used to modify a resource, using POST.
A GET request would result in a Method Not Allowed response.

This is also explained on Subbu's book, chapter 2.6 "When and How to
Use Controllers to Operate on Resources":

"Problem: You want to know how to tackle write operations that involve
modifying more than one resource atomically, or whose mapping to PUT
or DELETE is not obvious. Solution: Designate a controller resource
for each distinct operation. Let clients use the HTTP method POST to
submit a request to trigger the operation... If the outcome is the
modification of one or more existing resources, return response code
303 (See Other) with a Location with a URI that clients can use to
fetch a representation of those modifications."

> Not the semantics of a method invocation.  What does /cancel identify?
> Sounds to me like a method of tunneling DELETE through POST which
> identifies nothing, iow a procedure endpoint, which is characteristic
> of various styles but not of the REST style.  The hypertext constraint
> only makes sense if your resources make sense, in that their URLs are
> identifiers rather than endpoints.

If I understand correctly, you are saying that if I need to affect a
resource then I should use the uniform interface on that resource URI,
and not another URI.

> Which brings us to Chapter 5, and the short answer to your question:
> "POSTing to /cancel violates the Identification of Resources constraint,
> and is therefore unRESTful."  But I've found that just giving that
> answer tends to upset folks who've only read Chapter 5, then they get
> defensive about why can't they call their API RESTful, accusations of
> pedantry follow, and threads devolve into general ugliness, heheh...

After reading that chapter again I'm not sure my example violates
anything, but I'd love to get more clarification from you. Is it the
use of a verb in the URI? or not using the URI of the resource I'm
trying to modify directly?
--
Max Toro


On Sat, Dec 1, 2012 at 4:08 AM, Eric J. Bowman <eric@...> wrote:
> Max Toro wrote:
>>
>> What I'd love to get is an answer like: POST /orders/1/cancel is not
>> REST compliant because chapter x of Fielding's dissertation explicitly
>> or implicitly says it's not allowed or it's discouraged. After knowing
>> what is or isn't REST then I'd love to learn more about the pros and
>> cons of different architectural and implementation styles.
>>
>
> Well, what are you expecting to GET from /cancel, or are you just using
> that URL to invoke a procedure? If so, then there are a few places Roy's
> thesis admonishes against it in Chapter 6 -- the rest of REST is about
> positive, rather than negative, reinforcement of the identification of
> resources constraint. Suggested reading: 6.5.2; 6.2.1, in particular:
> "REST [defines] a resource to be the semantics of what the author
> intends to identify."
>
> Not the semantics of a method invocation.  What does /cancel identify?
> Sounds to me like a method of tunneling DELETE through POST which
> identifies nothing, iow a procedure endpoint, which is characteristic
> of various styles but not of the REST style.  The hypertext constraint
> only makes sense if your resources make sense, in that their URLs are
> identifiers rather than endpoints.
>
> Roy's thesis really must be considered in its entirety, to understand
> the uniform interface constraint (of which identification of resources
> is a sub-constraint).  Chapter 1 introduces the notion of applying
> design-by-constraint to networked software architecture, as inspired
> by Eames IIRC.  "A style is a named set of constraints on architectural
> elements that induces the set of properties desired of the
> architecture." (4.3)
>
> Chapter 2 defines terminology associated with networked software
> architecture, which is required for understanding Chapter 3, which lays
> out a methodology for evaluating various styles and applies this to
> several examples.  Most importantly, Chapter 3 identifies the
> constraints associated with various styles, and describes the properties
> they induce in a system (which may or may not be beneficial or
> detrimental to the system you're designing; remember there is no best
> architecture, only that which is best for your system).  Which is of
> course required for understanding Chapter 4.
>
> Chapter 4 considers the problems raised by the WWW, and suggests that
> the architecture may be improved by applying design-by-constraint to it,
> in order to address those problems.  First, by identifying the desirable
> properties of the early Web, and the constraints responsible for them;
> next, by extending that architecture by adding additional constraints,
> resulting in a new hybrid style consisting of aspects of existing
> styles. Of course, this is required for understanding Chapter 5.
>
> "REST provides a set of architectural constraints that, WHEN APPLIED
> AS A WHOLE, emphasizes scalability of component interactions, generality
> of interfaces, independent deployment of components, and intermediary
> components to reduce interaction latency, enforce security, and
> encapsulate legacy systems." (4.4)
>
> Which brings us to Chapter 5, and the short answer to your question:
> "POSTing to /cancel violates the Identification of Resources constraint,
> and is therefore unRESTful."  But I've found that just giving that
> answer tends to upset folks who've only read Chapter 5, then they get
> defensive about why can't they call their API RESTful, accusations of
> pedantry follow, and threads devolve into general ugliness, heheh...
>
> My point is, you'll have a much harder time trying to understand REST
> by being told bluntly what is and isn't RESTful, than you will by
> reading Roy's thesis in its entirety.  As computer science dissertations
> go, Roy produced a functional work of art, much as an Eames chair isn't
> just a piece of furniture.  Understanding what the constraints are, and
> where they come from, is vital to understanding how they're applied to
> the Web to derive REST, and why they must be implemented as a whole to
> achieve REST.
>
> Only then will it become apparent when they're being violated, as in
> the example given of POSTing to an unGETtable /cancel URL.  That level
> of understanding comes from the bottom up, not from the top down, IMO.
> Knowing what is or isn't REST depends on understanding the pros and
> cons of various architectural styles, because that's what constraints
> are, and constraints must be understood before their application to the
> Web as REST can be understood.
>
> More importantly, understanding REST as a style makes one a better
> architect, because sometimes it's advantageous to deviate from REST's
> constraints.  Which is why I'm always on about how saying something
> isn't REST is not a value judgment, just a fact.  Understanding Roy's
> thesis allows you to identify the constraints you have applied, and
> understand that as its own architectural style derived from REST, to
> use as a guide to developing that system -- but also to understand
> which desirable properties of REST you're forfeiting in the bargain.
>
> Making informed decisions about which constraints to apply, is making
> use of REST as a tool for long-term development.  It may not be
> feasible to apply all the constraints initially, if REST is truly what
> your system needs.  In which case your system design can account for
> this, becoming more RESTful over time, instead of painting yourself
> into a corner where the system needs re-architecting rather than
> implementing another constraint as an extension.
>
> -Eric

Thanks for you answer Erik. I don't want to repeat myself, so please
see my answer to Eric, I'd love to get your comments as well. Rather
than good or bad I'd like to determine if my example is REST or not.
--
Max Toro


On Sat, Dec 1, 2012 at 10:30 AM, Erik Mogensen <erik@...> wrote:
> This post is mostly aimed at Max Toro, but Eric provided a nice entry point
> for me :-)
>
> On Sat, Dec 1, 2012 at 8:08 AM, Eric J. Bowman <eric@...>
> wrote:
>>
>>
>>
>> Max Toro wrote:
>> >
>> > What I'd love to get is an answer like: POST /orders/1/cancel is not
>> > REST compliant because chapter x of Fielding's dissertation explicitly
>> > or implicitly says it's not allowed or it's discouraged.
>> >
>>
>> Well, what are you expecting to GET from /cancel, or are you just using
>> that URL to invoke a procedure? [...]
>>
>>  Suggested reading: 6.5.2; 6.2.1, in particular:
>> "REST [defines] a resource to be the semantics of what the author
>> intends to identify."
>
>
> Exactly.  And we don't know what the author intends to identify just by
> looking at the path /orders/1/cancel.
>
> Just looking at the syntax of a single request (e.g. the method POST and/or
> the path /orders/1/cancel) is not enough to determine if the system adheres
> to any particular architectural style.
>
> The author may well intend that /cancel identifies a resource, and allow
> lots of interaction in it.  It might even have an HTML representation, with
> a nice <form method="post"><input type="submit" value="CANCEL"></form> in
> it.
>
> But this is still not enough to determine if a system adheres to the
> constraints: For even though the server provides such hypermedia controls,
> media types and does everything "by the book", it is still up to the
> *client* to actually *use* these hypermedia controls.  In fact it is up to
> the author of the agent itself.
>
> If you write code in the client that hard wires a button called "cancel" to
> the "POST /orders/1/cancel" HTTP request then the client isn't really
> honouring the hypermedia controls laid out above.  If, however, it _soft
> wires_ the same button _because_ of the hypermedia control above, then
> you're doing it "more right" I would say.  The point is that the client
> should be written in such a way that it uses _only_ the hypermedia controls
> that it receives at run-time.
>
>> Roy's thesis really must be considered in its entirety, [...]
>
>
> +1 to such a degree that 1 > 1.  The rest of the stuff you wrote was great.
> I just want to highlight the incorrectness of the question, as others said
> earlier that REST doesn't say anything about if POST /foo is or isn't...
> For all we know /orders/1/cancel is a picture of a dog, or it could be a
> SOAP endpoint for a nice game of Global Thermonuclear War.
>
> The constraints of REST are too often thought / taught to deal with the
> server side, but in my experience, it has much more to do with the client
> side, how much knowledge the client has on things like:
>
> - what URLs can it use? (it shouldn't know any; but bind to one at run-time,
> preferably via a configuration parameter)
> - when it knows one URL (e.g. "/orders/1"), can it add "/cancel" to it to
> cancel it?  (no, unless it was told to add "/cancel" by a hypermedia
> control)
> - does it know the "type" of a resource, e.g. that /orders/1 is an Order
> (this is a point of contention on the list; browsers don't know about books
> or a bank account, but work fine nonetheless.)
> - when it does know the type of the URL is an order, does it pull up a
> pre-coded "order" UI (bad), or does it create a UI based on what it finds in
> the response (good)
>
>
> --
> -mogsie-

hello max.

On 2012-12-01 08:17 , Max Toro wrote:
> Thanks for you answer Erik. I don't want to repeat myself, so please
> see my answer to Eric, I'd love to get your comments as well. Rather
> than good or bad I'd like to determine if my example is REST or not.

i guess most people agree that the only reasonable answer to a question
such as "is URI X RESTful" is: "tell me more about your design."

i'd like to get one tiny bit of clarification from you: when saying you
have a resource X/operation, did you choose "cancel" on purpose as
something that could be mapped to a DELETE X fairly easily, or do you
also consider something such as X/additem, where the hypothetical
operation would not delete the resource, but change its status outside
of the CRUD realm?

thanks,

dret.

Did not choose DELETE because cancel does not delete the resource, it
executes some logic which in the end sets it's status field to
Canceled.
The implementation of PATCH with a body 'status=Canceled' can be
tricky if you also accept changes to other fields, which may or may
not have some logic associated to them. I think that using a
subresource as Nicholas Shanks suggested is a good solution, e.g.

PUT /orders/1/status

Canceled

The implementation can do something like this:

switch (value) {
    case "Canceled":
       cancelOrder(id);
    ...
}
--
Max Toro


On Sat, Dec 1, 2012 at 2:58 PM, Erik Wilde <dret@...> wrote:
> hello max.
>
>
> On 2012-12-01 08:17 , Max Toro wrote:
>>
>> Thanks for you answer Erik. I don't want to repeat myself, so please
>> see my answer to Eric, I'd love to get your comments as well. Rather
>> than good or bad I'd like to determine if my example is REST or not.
>
>
> i guess most people agree that the only reasonable answer to a question such
> as "is URI X RESTful" is: "tell me more about your design."
>
> i'd like to get one tiny bit of clarification from you: when saying you have
> a resource X/operation, did you choose "cancel" on purpose as something that
> could be mapped to a DELETE X fairly easily, or do you also consider
> something such as X/additem, where the hypothetical operation would not
> delete the resource, but change its status outside of the CRUD realm?
>
> thanks,
>
> dret.