Archive for February, 2008

PHP Appalachia 2008

Thu, 28 Feb 2008 6:19 UTC

Elizabeth Naramore announced PHP Appalachia 2008 earlier this week.

WHAT IS PHP APPALACHIA? A PHP unconference nestled in the Smoky Mountains, for those who like to camp or stay in a cabin, enjoy spending time with friends, and talking about PHP. As before, we will have a few presentations, but a lot of the time will be flexible and spent how the group sees fit at the time.

Details are still being finalized. Keep watching Elizabeth’s blog for more information, and I’m sure someone will update http://www.phpappalachia.org/ in the near future. :-)

UPDATE: Keith Casey also blogged about it. I was out of town for several days, so I missed lots. :-D

Comments No Comments  Permalink Permalink  Tags Tags: , , ,

Supporting PUT & DELETE in the Zend Framework

Wed, 27 Feb 2008 18:51 UTC

Creating a RESTful Web service is not simply about serving read-only content through HTTP GET requests. It’s about using the full range of HTTP’s constrained interface to allow clients to consume or create resources within your service. Take a look at CouchDB, for example. Its initial releases look very promising, and the server accepts GET, POST, PUT, and DELETE requests to manipulate resources in the system. I can’t wait until the project implements authentication and authorization features; then, it will look much more attractive for real-world use.

But I digress…

I’ve never been too happy with the Zend Framework’s RPC-based approach to creating RESTful Web services with Zend_Rest_Server, even though I have seen some good discussion about using routes and Zend_Rest_Server to create a resource-oriented architecture. Rather than get too in-depth about this issue, I’ll just point to this thread and save my full thoughts on Zend_Rest_Server for another day.

Suffice it to say, Zend_Rest_Server is not focused on resources but, instead, what you can do with those resources (procedures, methods, verbs) and also assumes you’re only ever going to provide an XML-based, read-only REST service. With REST, this is not the case, and, with the publication of the Atom Publishing Protocol (a protocol that follows the REST architectural style) as RFC 5023, now is the time more than ever to grasp the read-write capabilities of the RESTful Web.

But I digress (again)...

I’ve recently been wrapped up in an effort to design and implement a RESTful API using the Atom Protocol for a project at work. We are using the Zend Framework as the underlying framework for the project, so, in order to follow the Atom Protocol, I needed to support the HTTP methods PUT and DELETE. Apache can handle GET and POST easily because the request itself tells Apache the resource to use when processing the request. With PUT or DELETE, the resource identified by the request may not even exist, so Apache needs you to specify a script to process the request. To do this, I added the following lines to my virtual host configuration:

# PUT and DELETE support
Script PUT /index.php
Script DELETE /index.php

Now, all PUT and DELETE requests are handled by the Zend Framework bootstrap script and the dispatcher handles them in the same way it handles GET and POST requests.

To further support other HTTP methods and the REST architectural style, I’ve proposed the addition of the following methods on the Zend_Controller_Request_Http class:

  • isGet() – Was the request made by GET?
  • isPut() – Was the request made by PUT?
  • isDelete() – Was the request made by DELETE?
  • isHead() – Was the request made by HEAD?
  • isOptions() – Was the request made by OPTIONS?

Happy 10th Birthday, XML!

Sun, 24 Feb 2008 18:10 UTC

W3C XML 10th anniversary As you may have already noticed, I’ve started focusing a lot of my attention on XML, specifically with regard to the Atom Publishing Protocol. Now, please don’t confuse this attention with the giddy excitement of a newbie encountering XML for the first time and thinking of it as the greatest thing since sliced bread. On the contrary, that moment happened for me back in 2001 when I bought the first editions of Learning XML and XML in a Nutshell. Rather, I’ve simply come full-circle to a renewed appreciation for the syntax. In these days when people are singing the praises of JSON and other data interchange formats, I still think XML is the best format for exchanging data between disparate systems.

This year marks the tenth anniversary—or birthday, if you will—of the Extensible Markup Language. Version 1.0 of the W3C recommendation was published on February 10, 1998. In a press release covering this occasion, Tim Bray said:

There is essentially no computer in the world, desk-top, hand-held, or back-room, that doesn’t process XML sometimes. This is a good thing, because it shows that information can be packaged and transmitted and used in a way that’s independent of the kinds of computer and software that are involved. XML won’t be the last neutral information-wrapping system; but as the first, it’s done very well.

According to the press release, there will be “a variety of activities and events” planned throughout the year “to recognize and thank the dedicated communities and individuals responsible for XML for their contributions.” Since this is also the tenth anniversary of open source and the tenth anniversary of OSCON, I wonder if there will be any XML “birthday” festivities at OSCON this year. It already sounds like it’s going to be one big 10th anniversary party; I can’t wait to see who shows up for the fun. :-)

Comments No Comments  Permalink Permalink  Tags Tags: , , , ,

Namespace for URI Templates?

Thu, 21 Feb 2008 22:09 UTC

I was giving some thought to Joe Gregorio’s latest draft of URI Templates and considering how to use them with paginated feeds.

For example, I have an Atom Feed that includes the following link elements:

<link rel="first" type="application/atom+xml;type=feed" href="http://example.org/content"/>
<link rel="last" type="application/atom+xml;type=feed" href="http://example.org/content?idx=48336"/>
<link rel="previous" type="application/atom+xml;type=feed" href="http://example.org/content?idx=1"/>
<link rel="next" type="application/atom+xml;type=feed" href="http://example.org/content?idx=41"/>

It’s obvious that, to traverse the Feed, the Client need only change the “idx” parameter. So, why not tell the Client that they can do this with a URI Template?

To do this, I could use a template element, but in what namespace? That’s where my problem comes in.

I’ve searched all over the W3C URI mailing list, in addition to the Atom lists and all the usual suspects, but I haven’t seen where anyone has made a formal a recommendation.

I did stumble across a post by James Snell in which he proposed an approach to create a namespace to describe URI template variable names, but the post is stale (October 2006) and the approach doesn’t address the template itself.

So, without a good lead to go on and a strong desire not to create my own namespace, I sent an e-mail to Mark Nottingham asking if he would be interested in considering an update of the fh namespace to include a template element for this purpose?

For example:

<fh:template>http://example.org/content{-prefix|?idx=|index}</fh:template>

But then I found recent post by Joe Gregorio that doesn’t specifically address this, but does include in one of his examples the following snippet, defining a “t” namespace for the link_template element.

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
       xmlns:t="http://blah...">   
  <t:link_template rel="sub" href="http://example.org/edit/first-post/{-listjoin|;|id}"/>
...

I don’t know how I feel about having a general purpose template element in a separate namespace rather than having various namespaces define their own template elements. In the fh:template example, the template is within the “feed history” namespace, which gives it meaning; the URI template provided is for feed histories. If there is a separate namespace, then the template can lose context.

So, what do you think? Should there be a separate XML namespace to define URI templates? Is there an effort to do so, and where is the discussion occurring if there is?

Comments No Comments  Permalink Permalink  Tags Tags: , , , ,

Error Response Body For Atom

Thu, 21 Feb 2008 2:44 UTC

I’ve spent the last month deeply entrenched in the intricacies and idiosyncrasies of RFC 5023 and RFC 4287. You could say that we’re pretty intimate right now… but we haven’t yet made it to “third base.” I’m a gentleman, mind you!

I am, of course, talking about the RFCs for the Atom Publishing Protocol and Atom Syndication Format, and, during my study and research as I’ve been designing and architecting a RESTful API based on AtomPub, I’ve found that, while the AtomPub suggests and describes HTTP status codes to use in return for various behaviors, it does not, in fact, define the format of the response entity. The AtomPub even goes so far as to state in Section 5.5:

Implementers are asked to note that according to the HTTP specification, HTTP 4xx and 5xx response entities SHOULD include a human-readable explanation of the error.

Still, it doesn’t describe the format of that “human-readable explanation.”

This led me to do quite a bit of searching, which turned up some old posts on the atom-syntax mailing list that addressed questions about error responses:

On August 2, 2003, Joe Gregorio wrote in response to someone’s question about error repsponses:

You are right that the specification at this time does not cover error 
codes. In general the HTTP Status code should be the first line of 
defense, such as 403 Not Authorized, etc. There are errors that will 
need more detail than just the status code, and I see three possibilities:

1. Do nothing. That is, let the server decide the error code and 
formatting to return it in. For example, when you get a 404 on a 
web-site you often get an HTML page or a text/plain document. Not my 
favorite option.

2. Mandate a text/plain result that describes the problem.

3. The third option is to define an XML format for describing errors, e.g.

<error>
   <title></title>
   <description></description>
</error>

A few days later (August 8th), Joe asked the question, “How should errors be handled?” Sam Ruby replied:

Why reinvent?

http://www.w3.org/TR/SOAP/#_Toc478383507

I am often (rightfully) accused of being too obtuse. So let me be 
explicit in what I am suggesting here. Design a pure REST API. 
Where there seems to be places where "some invention is required", 
see if one can reuse precisely those elements - and only those 
elements - from SOAP. What you will end up with is a fully REST 
compliant interface which will enjoy wide tooling support.

My first reaction was, “Well, why the hell would I want to use SOAP? I’m trying to be RESTful here!” However, I don’t think what Sam meant was to follow SOAP verbatim but to, rather, borrow from SOAP in much the same way that the Atom community borrowed the WSSE username token from the OASIS Web Services Security committee and adapted it from a specification for SOAP services to a more RESTful application by passing the data through HTTP headers.

Essentially, the implication was to adapt a SOAP Fault to work in a RESTful way.

Diverging from the Atom format and adapting a SOAP format to fit my needs didn’t sit well with me, unfortunately. Rather, as I thought more and more about it, I realized that the Atom format itself suited my needs just fine. So, I decided to use an Atom Entry document that would list an atom:category element for every error that occurred while attempting to process the request (i.e. data validation errors, etc.) and send this back to the user with XHTML in the atom:content element that a client could use to parse and present a human-readable message to their users.

Ultimately, I was happy, could “rest” easy, and the end result looked a bit something like this. This example represents a potential XML entity body of a 400 Bad Request response resulting from invalid data submitted to the Atom service through POST or PUT.

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>An error has occurred</title>
  <id>tag:example.org,2008-02:1.0/errors</id>
  <updated>2008-02-20T17:08:33Z</updated>
  <author>
    <name>Ben Ramsey</name>
  </author>
  <category term="9311" label="Title field missing" scheme="https://api.example.org/1.0/categories/errors"/>
  <category term="9301" label="Author field missing" scheme="https://api.example.org/1.0/categories/errors"/>
  <content type="xhtml">
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p>Please correct the following errors:</p>
      <ul>
        <li>
          <a href="http://developer.example.org/errors/9311">
            Title field missing
          </a>
        </li>
        <li>
          <a href="http://developer.example.org/errors/9301">
            Author field missing
          </a>
        </li>
      </ul>
    </div>
  </content>
</entry>

Comments 2 Comments »  Permalink Permalink  Tags Tags: , , , , , , ,