Building a Hypermedia API in CouchDB

php|architectThe latest issue of php|architect includes an article of mine on Building a Hypermedia API in CouchDB. The article’s description:

This article demonstrates how to create a hypermedia data API using CouchDB, a document database and application server that is accessed through an HTTP API. URIs identify CouchDB resources such as databases, documents, attachments, and configuration sections. HTTP methods define actions on these resources. Requests from CouchDB clients—and responses to CouchDB clients—are self-describing through the use of request headers, response status codes, and response headers. However, CouchDB’s core API does not include hypermedia controls. This article will demonstrate how you can add hypermedia controls to your CouchDB application through the use of show functions, list functions, document update handlers, rewrite rules, and a virtual host or a reverse proxy.

The article uses the JSON Hypermedia API Language (HAL) draft media type (application/hal+json). This allows for the creation of a generic hypermedia API. HTTPie is used to demonstrate interactions with the hypermedia API.

The article includes a companion proof of concept Hypermedia API built in CouchDB which is available on GitHub. PHP, the Doctrine CouchDB Document Object Mapper (ODM), and Cilex are used to push the proof of concept application to CouchDB. PHPUnit and Guzzle are used for a suite of tests that exercise the hypermedia API served directly from CouchDB.

This same issue of php|architect also includes the following articles:

  • Using SimpleDB by Eli White
  • Stored Procedures and Variables in MySQL by Chris Tankersley
  • Performance: Performance Concepts from Those That Know by Matthew Setter
  • Outside the Box: Method Overloading by Joshua Thijssen

PHP 5.4 Cheat Sheet from DZone Refcardz Published

I’m happy to announce that my PHP 5.4 Cheat Sheet from DZone Refcardz was published today. This is a major update to DZone’s existing PHP Refcard with material for PHP 5.4 added. In anticipation of this release, DZone interviewed me about this update. From the interview:

The PHP 5.4 Refcard is for beginner to intermediate PHP developers. It’s not for complete beginners as readers will need to have some knowledge of things like basic control structures and data types. More experienced PHP developers should find this Refcard helpful, too. For example, there’s a section on security that talks about filtering input, escaping output, and password encryption.

Being a cheat sheet, there was only so much space available and a lot of great content had to be cut. Also from the interview:

The biggest section to be cut was the one on classes and objects. Some of the object-oriented programming features not included were property/method visibility, class constants, static properties/methods, abstract classes, abstract methods, interfaces, traits (introduced in PHP 5.4), late static binding, type hinting, namespaces, autoloading, exceptions, and the Standard PHP Library (SPL). This section alone probably could have fit in an entire Refcard. Some other content that was cut included more details on data types, how to use database transactions with PDO, details on working with the various string syntaxes, more detail on arrays, more examples of working with functions, how to serve static assets using the built-in web server, and further details on working with dates and times.

A big thanks to Engine Yard for sponsoring this Refcard!

Entity Relationships in a Document Database at ZendCon 2012

Here are the video and the slides from my Entity Relationships in a Document Database at ZendCon 2012.

Some of the tools mentioned in the presentation:

Domain-Driven Design at ZendCon 2012

Here are the video and the slides from my Domain-Driven Design talk at ZendCon 2012.

If you’re interested in learning more about this topic then I’d recommend reading the original book on the topic of Domain-Driven Design by Eric Evans. Eric also runs a training company called Domain Language which offers training on Domain-Driven Design. I had the privilege of attending his four day hands-on immersion class which I would highly recommend for anyone who wants to take a deep dive into Domain-Driven Design.

Here are some additional resources that may be helpful:

Statement on Burlington Telecom and its Governance

Almost exactly a year ago I was appointed by the City Council of the City of Burlington, Vermont to the Telecommunications Advisory Committee. In this volunteer position, my role has been to advise the City Council on matters related to Burlington Telecom, a municipally owned telecommunications services provider. At the last regular meeting I was elected Chair. Soon after, I learned that the City Council has plans to potentially dissolve this committee at the next City Council meeting this coming Monday, October 15th. We’ve drafted the following statement (also available on the BTAC Documents page) to be read at this meeting which expresses my thoughts on this potential decision.

To the Burlington, Vermont City Council on October 15th, 2012:

This is a statement from the current members of the Burlington Telecom Advisory Committee—often referred to as BTAC. The BTAC is a citizens committee created by the Burlington City Council and its Transportation, Energy, and Utilities Committee. Formed in 2004, the BTAC was designed to “include a measure of citizen input and oversight into the development and deployment of the telecommunications project.”

It is our understanding that the City Council is considering dissolving the BTAC and transferring its responsibilities to the Blue Ribbon Committee. The decision on whether or not to dissolve the BTAC is a decision to be made as part of a political process. We do not see the BTAC as a political entity, but rather as a governance and oversight body. As such, this statement is not intended to influence your decision one way or another. However, we feel that it is important to share our perspective on the future of Burlington Telecom and its governance in the absence of a citizens committee.

The governance and oversight of Burlington Telecom has long been a difficult and complex issue. In 2009, the City Council formed the Blue Ribbon Committee with two primary responsibilities: assess the viability of Burlington Telecom and assess all available options for the financial structure of Burlington Telecom. Due to the nature of the Blue Ribbon Committee’s work, much of its activity has been done in secret executive sessions.

This is not meant as a criticism of the Blue Ribbon Committee. We understand the reasoning behind this approach. The Blue Ribbon Committee feels that public knowledge of some information might put Burlington Telecom at a competitive disadvantage and that it would not be in the public interest for this information to be publicly known. We also understand that the Blue Ribbon Committee feels that conversations with potential Burlington Telecom investors, partners, or purchasers must be kept confidential, at least initially, in order to obtain the best possible terms for the citizens of Burlington. These are arguably good reasons for secrecy around the Blue Ribbon Committee’s work.

In contrast to the Blue Ribbon Committee, the BTAC rarely holds executive sessions and almost all of its activities are open to the public. There are many areas of Burlington Telecom’s governance where transparency better serves the interest of the public. Our concern is that, without the BTAC, transparency into Burlington Telecom’s operations will become almost non-existent. We urge you to consider the importance of transparency and to move forward with options that increase, not decrease, the level of transparency around Burlington Telecom.

The timing of this action is unfortunate. At its last regular meeting, the BTAC elected a new Chair who outlined three main goals for the BTAC moving forward. These goals were: improve communication between the BTAC, the City Council, and the Blue Ribbon Committee; increase public dialogue to channel input to and from the City Council; and define a clear role for the BTAC. We were looking forward to acting on, and have taken initial steps towards, these goals.

We joined the BTAC because we care about Burlington Telecom and the positive impact that we believe it can, and does, have on our city. Burlington Telecom is not just another telecommunications provider. It is critical infrastructure for the 21st century that is owned by us, the citizens of Burlington. This Fall, Burlington Telecom is rolling out 1 Gbps symmetrical broadband speeds. We are one of a handful of cities in the country with access to this type of bandwidth, putting us at a distinct economic advantage.

Market forces alone have failed to create the broadband infrastructure we need. According to Akamai’s Q1 2012 “State of the Internet” report, the United States is ranked 12th in broadband speed, with an average speed of 6.7 Mbps. This Fall, Burlington citizens and business will have access to broadband speeds 150 times as fast as the national average. In comparison, South Korea is ranked highest with an average broadband speed of 15.7 Mbps. Burlington citizens and business will have access to broadband speeds 65 times as fast as the fastest country’s national average.

Burlington Telecom is a critical part of our city’s infrastructure. It belongs to the citizens of Burlington. In order for us to continue to benefit from this infrastructure, it must be governed transparently. Thank you for your time.

Northeast PHP Tickets

Tickets for the Northeast PHP Conference will be going on sale this Thursday, June 28th at a cost of $99 per person. The conference will be taking place on Saturday, August 11th and Sunday, August 12th at Microsoft’s NERD Center in Cambridge, MA and will feature talks from dozens of speakers across four tracks. This event is being organized by Boston PHP (a non-profit organization) and other user groups from the northeast region—it is completely volunteer-driven with the help of some generous sponsors. Tickets will likely sell quickly, so be sure to reserve your seat early!

Sponsor the Boston PHP Northeast Conference

There are several sponsorship opportunities available for the Boston PHP Northeast Conference. Sponsoring this community organized event is a great way for your organization to demonstrate its support for the PHP community. The event will be taking place on on Saturday, August 11th and Sunday, August 12th at Microsoft’s NERD Center in Cambridge, MA and will be focused around four tracks:

  • Core PHP
  • Web Development
  • Training
  • User Experience (UX)

We are primarily looking for in-kind sponsorships. Some items available to sponsor include (items are subject to change—this is not a final list):

  • Gold:
    • Speaker Dinner
    • T-Shirts for Attendees
    • Evening Event on Saturday
  • Silver:
    • A Speaker’s Travel Expenses (see below for more details)
    • Breakfast on Saturday or Sunday
    • Lunch on Saturday or Sunday
  • Bronze:
    • Coffee on Saturday or Sunday
    • Afternoon Snacks on Saturday or Sunday
    • Raffle Items (e.g. books, magazines, training, software)

We’re also looking for media sponsors, if you’d like to help promote the event. All of the sponsorship levels (Gold, Silver, Bronze, and Media) include a sponsorship listing on the event website and the ability to send us promotional swag to give to attendees. The Gold, Silver, and Media sponsorship levels include some visual presence at the event. Gold sponsors will get more prominent visual presence and a mention during the opening and closing keynotes.

One great way that you can sponsor this event is by helping to pay for a speaker’s travel expenses. A couple speakers who are looking for travel support include Stefan Koopmanschap and Michelangelo van Dam.

Please contact me if you’re interested in sponsoring.

Entity Relationships in a Document Database

This week I attended and presented at CouchConf Boston. I’d like to thank Couchbase for inviting me to speak—it was a great opportunity to meet other CouchDB and Couchbase users. I’ve posted the slides from my Entity Relationships in a Document Database talk to Speaker Deck (and SlideShare, if you prefer):

The presentation covered four patterns for modeling entity relationships in document databases such as CouchDB and Couchbase:

  • Embedded Entities
  • Related Documents
  • List of Keys
  • Relationship Documents

See the presentation for more details. This topic is also covered in the MapReduce Views for SQL Users chapter in the second edition of Writing and Querying MapReduce Views in CouchDB.

Day Against DRM

Day Against DRM vertical bannerToday is the Free Software Foundation’s (FSF) International Day Against Digital Restrictions Management (DRM). This being done as part of the FSF’s Defective by Design anti-DRM campaign. To celebrate Day Against DRM O’Reilly Media is having a sale of 50% off all of its ebooks (which are all DRM-free) including Writing and Querying MapReduce Views in CouchDB and Scaling CouchDB. From O’Reilly Media:

In Celebration of *Day Against DRM*
Save 50% on ALL Ebooks & Videos

Having the ability to download files at your convenience, store them on all your devices, or share them with a friend or colleague as you would a print book, is liberating, and is how it should be. If you haven’t tried a DRM-free ebook or video, we encourage you to do so now. And if you’re already a fan, take advantage of our sale and add to your library.

For one day only, you can save 50% on all O’Reilly, No Starch, and Rocky Nook ebooks and videos. Use code: DRMFREE

Ebooks from are DRM-free. You get free lifetime access, multiple file formats, free updates. Deal expires May 4, 2012 at 11:59pm PT and cannot be combined with other offers.

Speaking at CouchConf Boston

I will be giving a presentation on Entity Relationships in a Document Database at CouchConf Boston on May 15th. The talk description:

Unlike relational databases, document databases like CouchDB and Couchbase do not directly support entity relationships. This talk will explore patterns of modeling one-to-many and many-to-many entity relationships in a document database. These patterns include using an embedded JSON array, relating documents using identifiers, using a list of keys, and using relationship documents.

Additionally, this talk will address how each entity relationship pattern equates to its equivalent in a relational database. I’ll be discussing the relevant differences between document databases and relational databases such as:

  • Document databases do not have tables
  • Each document can have its own schema
  • There is no built-in concept of relationships between documents
  • Views/indexes are queried directly instead of being used to optimize more generalized queries
  • A column within a result set can contain a mix of logical data types
  • There is typically no support for transactions across document boundaries

This talk is based on the MapReduce Views for SQL Users chapter that I’ve added to the second edition of Writing and Querying MapReduce Views in CouchDB.