[wp-hackers] Help with the API on WordPress.org?

[Mike Schinkel]

"Peter Westwood" <peter.westwood at ftwr.co.uk> wrote:
> Yes being RESTful makes caching easy but you don't always need caching.

No you don't, but you should always plan for it in case you need it.
Implement using a RESTful approach and that planning becomes "free."

> Caching is something that you consider when performance
> becomes an issue. You should never optimise early and
> relying on caching is optimising early.

While I agree with the principle of not optimizing early, I don't agree that
designing for being able to cache is optimizing early. I'm also very sure
that you get a lot of people who would debate you on that assertion over at
the rest-discuss list (http://tech.groups.yahoo.com/group/rest-discuss/)
because that is one of thing that RESTians argue makes REST superior to
RPC-over-HTML.

Basically designing for being able to cache is an architecture concern, not
an optimization concern. Tuning the caching too early is an optimization
concern.

However in this case if I search for "Category" via the WordPress.org Plugin
API multiple times in a short period of time it makes absolutely no sense
for the client to contact the server again each time. It causes the servers
to work unnecessarily and it makes the user experience slower, all when it
simple HTTP header could tell the client to cache for a reasonable amount of
time (10 minutes, 1 hour, 1 days? Not sure how long yet, as that's the
optimization part.)

> I like the way you abuse REST here.
> One of the key principles of REST is that
> it is stateless and here you go introducing
> state to your REST transactions!

Au contraire my good man!  It is not me abusing the principle of
statelessness, it is you misunderstanding the principle of statelessness!

That's okay though, it took me several months on the rest-discuss list to
get it banged into my head so I don't expect many others would get it prior
to similar pain. :-)

First off, the way I described transactions is a RESTful best-practice.
That same approach was advocated in the RESTian's bible, "RESTful Web
Services" By Leonard Richardson and Sam Ruby and published by O'Reilly:
http://oreilly.com/catalog/9780596529260/ You can find it on page 231 in
Chapter 8 "REST Best Practices" section "Transactions."  It has also been
advocated as a best-practice on the rest-discuss list ad-nauseum, here being
one example:

   http://tech.groups.yahoo.com/group/rest-discuss/message/7781

Anyway, as for understanding statelessness your statement confuses state on
the server with state on the client. If you couldn't change state on the
server you'd rarely ever be able to do anything useful on the web. One
example of such state changing, which if a very common, is a shopping cart.
It doesn't not violate REST's statelessness principle to add an item to your
shopping cart and have that state stored on the server. What DOES violate
REST's statelessness principle is if you were to store the items in the
shopping cart in a cookie on the client.
Using cookies violates REST, period. On page 406 of "RESTful Web Services":
"The use of the 'Set-Cookie' header violates the principle if
statelessness." Storing a shopping cart ID that links back to the server
even violates statelessness but we do it on the "human" web because it
improves user experience even though it is less RESTful. For RESTful
services all state that the client needs to know to interact with a server
should be encoded into the URL.

In a RESTful shopping cart app, you've have the following:

   POST http://example.com/cart/new
      {cart-data}
      -> returns 201, Location:http://example.com/cart/{cart-id}

   POST http://example.com/cart/{cart-id}/items/new<http://example.com/cart/%7Bcart-id%7D/items/new>
      {item-data}
      -> returns 201, Location:
http://example.com/cart/{cart-id}/items/{item-id}

So as you can see, using REST in this way does not in any way violate the
statelessness principle.

BTW, the book "RESTFUL PHP Web Services" by Samisa Abeysinghe published by
PACKT http://www.packtpub.com/restful-php-web-services/book is mostly a
regrettable book filled with lots of little errors and where the author has
very little apparent understanding of the nuances of REST.  I was actually
sent a copy of that book by the publisher at his offer in exchange for
writing a blog post about it (since I've blogged about REST and PHP in the
past) and I'm having a hard time making myself write that post because I
can't say much good for the book. I will say it has some useful code (that I
assume works) that will give you some shortcuts, but don't under any
circumstances read PACKT's  "RESTFUL PHP Web Services" *before* reading
O'Reilly's "RESTful Web Services."

>> My response is "Every API is a human-use API, or at least should be
>> considered one."
>>
> Not really, you should develop the API you want to use in
> this situation. It is very difference from someone providing
> an API on there service which should be designed to be human
> usable.

I don't follow your logic here.

> This API is very specific in its design and usage.

Which is a shame since it could be used for so much more.

> It supports it's use case very well.

I assert that it does not support its use case as well as it (easily) could.

> Except that API would have never been written in the first
> place as there was no use-case for it in the first place!

But that's the difference between a visionary API and one that is not.  Yes,
you can easily argue that this API didn't have another use-case, and what I
argued was that because of that short-sightedness, it likely never will (as
is.)

BTW, please take all my words to be "matter of fact" and please don't infer
any sarcasm or condescension. I very much mean to be respectful and just
want to have a debate on the technical merits but know that sometimes it can
be very hard to do that on a mailing list when you don't know the person.

It's my belief that optimizing the sociology of technology is the key to
value creation now and in the foreseeable future. Twitter is a perfect
example of a service that got so many things right; the use-case, the
usability, the API, etc. WordPress has gotten so many things right (UI
usability, use-cases, the hook system, etc.) it's a shame for the
WordPress.org API not to be able to be more.

> I would recommend if you want to do this to start off
> by creating your own site which hosts the services to
> prove there usefulness.
> All the source data you need is publicly available.

I'm actually working on exactly that right now! :-)

> You also need to recognise when you are developing a
> private api but making it available publicly and then
> you develop the api very close to your use-case.

We may end up agreeing to disagree on this but I strongly believe that even
private API should be designed RESTfully. Hopefully you'll see the benefits
after I launch my version. (Forgive me, but if we do disagree now my
assumption is you'll come around within in a few years to appreciating the
value of REST as it proliferates and more people start actually understand
it rather than assume they understand it. Note that latter part is not me
being snarky, it's the process one takes on the rest-discuss list where the
RESTians constantly tell you "You don't get it!" until after a long time you
finally do. :-)

-Mike Schinkel
http://mikeschinkel.com

P.S. One final note: even though I advocate for "better" I do understand
"what gets it done."  But there's a difference between saying "That is just
what it took to get it done" and "What it took to just get it done is the
best way to do it."  It's only the latter type of assertions I will usually
challenge.