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

[Peter Westwood]

On 2 Jan 2009, at 05:56, Mike Schinkel wrote:

> "DD32" <wordpress at dd32.id.au> wrote:
>> Because it has no need to be (RESTful)?
>
> Oh, now there you've gone and done it. You've just unleashed my  
> "RESTful
> Zealot" persona and now I feel compelled to enter proselytizing  
> mode. :-)
>
> By comparison, the RESTians would call the style of the  
> WordPress.org Plugin
> API "RPC over HTTP" were most of the benefits of the HTTP web are  
> provided
> automatically.  Let me give you once such real and tangible benefit of
> having a RESTful API for Plugins on WordPress.org vs. using the  
> existing RCP
> over HTTP API: "HTTP caching."
>
> Here one BIG reason why your API *does* need to be RESTful.  Using the
> approach I suggested you get HTTP Caching "for free."  Said http  
> caching
> would 1.) reduce the load on the WordPress.org API servers and 2.)  
> it would
> speed the end user experience as they page through the multiple  
> pages of the
> same results. Yes, you could cache the values you retrieve from  
> your API but
> you'd have to write caching code and caching on RESTful APIs comes  
> with
> (almost) no extra code.
>
> And that's the thing about RESTful APIs; you get so much of what you'd
> otherwise have to write for free. Basically anything that  
> understands the
> HTTP web can also understand a RESTful web service and add additional
> functionality, such bookmarking services, etc.
>

Yes being RESTful makes caching easy but you don't always need caching.

Caching is something that you consider when performance becomes an  
issue.

You should never optimise early and relying on caching is optimising  
early.

> Of course allowing for retrieval of information about a list of  
> plugins
> given the list of plugin slugs could easily exceed 2000 characters  
> (it is
> ironic that that was my needed use-case.) The way that could be  
> addressed
> would be to allow them to be encoded into the URL for short lists  
> and for
> longer lists split into two HTTP transaction, i.e.
>
>    #1 - POST to "http://restapi.wordpress.org/plugins/sets/new"  
> with the
> POST body being "plugin_list=plugin1&plugin2&plugin3&...&plugin"
>
> The response to the post would be "201 Created" (or maybe "303 See  
> Other",
> I'd need to ask on the rest-discuss list) with a header of "Location:
> http://restapi.wordpress.org/plugins/sets/{set-id}" where {set-id}  
> would be
> the unique ID given to the that set of plugins on the server. Note  
> that the
> first time this POST was submitted for a list of plugins it would  
> create the
> new set; each time after it would simply retrieve the set ID for the
> existing set.
>

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!


>
>> Well, The fact its not a human-use API really..
>> It accepts PHP, it gives back PHP, It makes sense
>> to test from within PHP,
>
> 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.

This API is very specific in its design and usage.

It supports it's use case very well.

>
>> And since the primary use of it is for WP, calling
>> plugins_api('action', (object)array('test'= > 'a'));
>> makes a lot more sense than allowing for browsers/etc.
>
> I'd (respectfully) argue that your implementation will (almost)  
> certainly
> doom it to be so (i.e. only ever used by plugins_api().)
>
> However I can actually envision lots of different use-case for the  
> WordPress
> Plugin API if it were more accessible.  For example, if there were  
> a RESTful
> API with an RSS representation format then plugin authors could use  
> an RSS
> Widget to list their own plugsin on their own blog. Here's the
> (hypothetical) URL that would list your (dd32's) plugins:
>
>    http://restapi.wordpress.org/authors/plugins/dd32.rss
>
> See how the serendipity of the RESTful approach starts to expose  
> itself? :-)

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

>
> The nice thing about APIs on the server is they are just interfaces  
> to a
> back-end so it's possible and easy to implement multiple APIs to  
> the same
> back-end. Which brings me back to my offer to implement a truly  
> RESTful API
> for WordPress.org plugin repository: I've got lots of the code already
> implemented from other projects; so who do I propose this to? :-)
>
>

Your welcome to do this.

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.

In general while I agree with you that REST is a good approach for  
public web-service APIs you need to recognise when you are developing  
one of them first.

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.

westi
-- 
Peter Westwood