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

[Mike Schinkel]

 "Peter Westwood" <peter.westwood at ftwr.co.uk> wrote:
>> Serialised data is the standard response type I would use with php.

Actually, there are standards and then there are "Standards."

You were referring to the format you use by convention for your convenience
and which is also arguably a defacto-standard because of the functional
inclusion in PHP. I was referring to the "MIME Type" standards (
http://en.wikipedia.org/wiki/Internet_media_type) as set forth the the
Internet Assigned Numbers Authority (IANA) and as recognized as
authoritative by the W3C and all other Internet-oriented standards bodies.
You can see the list of recognized MIME types here:

   http://www.iana.org/assignments/media-types/

After a quick review I don't see anything that mentioned serialized PHP so
it appears that it's use as a representation for HTTP request responses has
not established any widespread use, at least not by anyone significant who
values web standards.

Since WordPress is using serialized PHP for web services over the open
Internet and probably will be do so even more in the future so it would be a
really good idea to register as a well-known MIME Type, probably
"application/serialized-php."  Registration procedures and information are
here:

   http://www.iana.org/assignments/media-types/application/
   http://www.iana.org/cgi-bin/mediatypes.pl
   ftp://ftp.rfc-editor.org/in-notes/rfc4288.txt

Prior to an accepted registration "application/x-serialized-php" would be
acceptable but it's a good idea to get the non "x-" version registered
before proliferation of software that uses the "x-" format which is a best
practice as mentioned in the registration documents. BTW, it seems I'm not
the first to suggest "application/x-serialized-php":

   http://sandeep.shetty.in/2006/04/yahoo-unrest.html

Actually I just checked the response type for the web service at
http://api.wordpress.org/plugins/info/1.0/ and that web service is not
following the HTTP standards recommendations with respect to the
"Content-Type" requirement. Its returned content type header is the
following which tells a client/user agent that what is returned should be
interpreted as HTML, not as serialized PHP:

   "Content-Type: text/html; charset=UTF-8"

According to the standard in section 7.2.1:

   "Any HTTP/1.1 message containing an entity-body SHOULD
    include a Content-Type header field defining the media
    type of that body. If and only if the media type is not
    given by a Content-Type field, the recipient MAY attempt
    to guess the media type via inspection of its content
    and/or the name extension(s) of the URI used to identify
    the resource. If the media type remains unknown, the
    recipient SHOULD treat it as type "application/octet-stream".

For more details on this, see:

   http://www.w3.org/Protocols/rfc2616/rfc2616-sec7.html#sec7.2.1
   http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17
   http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.7

Today (at least) the WordPress Plugin API really should set the content type
header (something like) this:

   "Content-Type: application/x-serialized-php; charset=UTF-8"

Later, upon successful MIME type registration, if could return this:

   "Content-Type: application/serialized-php; charset=UTF-8"

These standards, BTW, are for maximum interoperability. You might say "But
we don't need that because it is a *private* API" to which I'd reply
"Nothing is private that goes unencrypted over the public Internet." More
specifically why you should care is some firewalls doing active monitoring
might block serialized PHP that is identified as HTML because it doesn't
look at all like HTML and thus (as far as the firewall is concerned) could
potentially be a virus. So I repeat: "For maximum interoperability, follow
the standards."  Besides, in this case it would be cake to fix the Content
Type header on the WordPress.org server.

> Please don't use WordPress in your domain name [1]

You mean like http://advancedwordpress.com/? :-)

Yeah, I know about [1].  I bought the domain name for a potential book I'm
considering writing with a planned title of "Advanced WordPress" and it just
didn't seem to make sense to use different name for the domain that the
planned book title. What's more usage of trademarks in book titles has
pretty much always been given fair-use legal protection. I don't know if it
will definitely write the book but if it gets to that point it will be made
clear that it is a book about advanced WordPress techniques and not
something blessed or otherwise legally related to WordPress.org/.net.

BTW, my reason for considering writing a book is because I'm probably going
to write a lot of the content anyway for my own learning, why not make it
generally available? What's more, if I do it I will hope to lean on everyone
else who has come before me preparing excellent examples of advanced
Wordpress Techniques with full attribution and only with approval. BTW, by
"advanced" I mean mostly writing plugins, not being a hipster marketer who
at best can install the thing.  Maybe it should be called "Professional
WordPress" or "Programming WordPress"; whatever the case it would still
ideally contains the name "WordPress" in the domain so same issue. (Wishing
there were a ".book" TLD, that's resolve this issue here for sure.:-)

OTOH, the API doesn't *have* to live there long term if its a problem but it
seemed the most logical place to put it given the domains I have.

> Is the code available anywhere for people to build on?

Not yet, I want to flesh out the RESTian library before I release it. It
really needs a lot of thought before it gets unleashed to the world and it
starts proliferating, and I don't want to have to support older versions. I
also recently did something related called SimpleUrlMapper (
http://code.google.com/p/simpleurlmapper/) and want to try to integrate the
functionality of the two.

IF there is significant interest from others I'll be motivated to get it
done sooner than later. :-)

-Mike Schinkel
http://mikeschinkel.com