Introduction

I recently grabbed the pre-print release of Lorna Jane Mitchell’s new book “PHP Web Services: APIs for the Modern Web”, now available in Print and Ebook formats through O’Reilly. APIs are such an integral part of modern web application development. Lorna herself specialises in API development and integration, rarely working on anything that could be called front-end.

Every system I have worked on recently has been heavily API based. With the current trend in single-page JavaScript web applications and client-side MV*, the server is being relegated more and more to the role of data provider through custom APIs.

Content

In the preface, Lorna enumerates many scenarios in which building APIs is a prudent strategy and why PHP is a pragmatic way to “solve the web problem”; being built with the web in mind from the beginning it comes with many useful tools for delivering and consuming web services built in.

With this introduction (as well as the usual typographical conventions) out of the way, we are thrown straight into the nuts-and-bolts of the basics of HTTP request/response and how the browser/web server is analogous to the API consumer/provider we will be building. A very practical and useful part of the chapter is the introduction to a number of tools and techniques for making and inspecting requests against HTTP servers, I have personally used the section on Curl as a reference a number of times already.

No introduction to HTTP, especially as a platform for APIs, would be complete without an explanation of the HTTP verbs and this book doesn’t disappoint, with a thorough explanation of the common verbs and PHP code examples of their usage. Delving deeper into the HTTP protocol, we find a much more comprehensive look at request and response headers, a look at a number of common headers and a detailed look at the very important, but in my experience – underutilised, Accept header for content negotiation, including example code to parse it correctly taking into accounts the weighting of the preferences. This is great low level information for building a flexible API service.

A chapter each is given to XML and JSON data formats, the advantages and disadvantages of each. Asking the question, “which format is superior?” (Hint: it depends); Some useful guidelines regarding the scenarios in which each format may be an appropriate choice are provided. There are, of course, code snippets showing how to work with each format.

The chapter on RPC and SOAP provides a substantial look into these styles of services with examples of real-world APIs, snippets to create and consume them and tools to make working with them more friendly. In spite of the book appearing somewhat biased towards REST style services (or maybe that’s just me), this chapter is full of great information and tips for REST and SOAP style services, but if this is your primary interest there are probably better books.

The REST chapter brings together many of the concepts explored in the previous chapters about HTTP, verbs, headers, URLs and data formats to describe REST services in a useful, accurate and fairly succinct way. Thorough explanations of how to implement the standard CRUD operations so fundamental to REST are provided. Special mention is also given to hypermedia and content negotiation/media types, which are important aspects of “pure” REST services. Ever pragmatic, the chapter concludes with a section reminding readers to remember not to be caught up in the “trendy”, and that it is more important for an API to be “useful” than it is to be “RESTful”.

The debugging chapter looks into what to do when it all goes wrong. As APIs are generally hidden behind the actual application interface the techniques for debugging them can be a bit different. Lorna introduces a couple of tools for inspecting the requests and responses on the wire to allow the tracking of anomalies without interrupting the data flow and breaking request/response formats.

Towards the end of the book, we step away from the code for a couple of chapters and discuss the design decisions based on the options provided earlier in the book. Including chapters discussing robust, predictable, user/developer friendly APIs, handling errors and writing documentation.

Conclusion & Recommendations

That was longer than I intended, but I see that as testament to the breadth of information contained within the seemingly modest tome, every chapter has something. Weighing in at a little over 100 pages “PHP Web Services” provides a great foundation to the practicalities of using PHP to build modern web services.

I feel the target audience for the book is the PHP developer who has built a few web sites, but never looked much deeper into the workings of the HTTP protocol and its implications. It provides a broad overview of important concepts, but probably doesn’t dive deep enough for the seasoned professionals. The code snippets are just that, snippets, a demonstration of the core concept, they are not full libraries that should be dropped directly into production code.

All in all, I think the book provides a solid overview of many of the considerations of web service development and would be a great guide to anyone venturing into building such services in PHP.

As I previously blogged, I’ve recently changed blogging platform to use a static generator. One of the disadvantages that comes with serving only static files is a lack of interactivity; There is no server-side scripts to handle things like comments. The most common solution is to use a third party service, such as Disqus that provides a JavaScript widget for you.

Of course, as Chris Shiflett in his (now traditional :P) Ideas of March post espouses, the disadvantage of any third party service is the lack of data ownership; “You never know when it’s going to disappear.” citing the recent announcement that Google Reader is to be shut down. This is why I am reluctant to implement such a solution. And given Lorna Mitchell’s suggestion, “don’t read the comments”, I have to wonder if having comments is worth the effort involved?

For now, it looks like I’m going to remain comment free. Which is a shame. The occasional grateful comment from a random stranger on the Internet has a certain way of almost making up for some of the not-so-nice the Internet thrusts upon us. Without this feedback, where’s the love?

Both Lorna Mitchell and Rob Allen (in his response) assert that they intend to sometimes “turn off comments and encourage others to respond by writing […] on their own blog.” I think this is a fantastic idea (I’m doing so right now), though I do have some concern about how well fragmented blog posts can coalesce into a meaningful conversation, “trackbacks” were an attempt at solving this issue, but I’m not sure that worked too well.

This is one advantage the “walled gardens” currently hold – they have the ability to aggregate the posts into a single congruous conversation.

If you have any solutions to the fragmented conversation problem, write a response on your blog and I’ll… Probably never see it… Ping me on twitter, maybe?

Wow, it’s been over 3 years since my last post! And, like so many entertainment franchises, I think it’s time for a reboot. I stopped blogging when I moved away from PHP because I no longer felt confident enough in my work to open up anything I was doing to any kind of public scrutiny. Having since (mostly) returned to PHP, doing some consulting and contracting and embarking on a venture of my own, I feel it is time once again to put some of my experiences and thoughts into writing.

To facilitate this, and because my Wordpress install was so hideously out of date, I’ve decided to changed to a static blogging solution: Octopress. As such, the blog is currently without much of a design. This may (or may not) be remedied at a later time. I will write in more detail about the platform and the migration in a future post.