While this article, linked here, does a good job of explaining things I’m going to quickly summarize what this is all about. SOPA is an acronym for the Stop Online Piracy Act (its text can be read here: http://thomas.loc.gov/cgi-bin/query/z?c112:H.R.3261: ), and is a proposed bill aimed at cracking down on copyright infringement by restricting access to sites that host or facilitate the trading of pirated content. On the whole this does not seem like such a bad thing and almost everyone would agree that this is a worthy goal to try and attain. The problem, however, is how this proposed bill goes about obtaining this goal. Any site could be in violation of the law if they “facilitate” copyright infringement. The problem with this is that the word “facilitate” invites very broad interpretations of its meaning. In addition, any site accused of being a “facilitator” will have all services – network connectivity and payment services, among others – cut off in an “ask questions later” approach. The filing of false notifications against an online property is a crime, but the burden of proof that a crime was not committed lies with the site that has just been taken down.

This is a horrible piece of proposed legislation that will very likely have a far-reaching and potentially-devastating impact on the internet as a whole. As a professional software developer that has made his living developing internet applications for the past 13 years, and did so un-professionally for several years prior to that, I cannot allow this legislation to become law.

How can you help stop SOPA?

Lamar Smith has been the Republican Congressman for the 21st congressional district in Texas since 1987 and is the individual that introduced the SOPA legislation. Well, my good friend Richard Morgan, a fellow PHP developer, is running against him in the upcoming primaries and needs your help. Richard Morgan opposes SOPA and will make it a priority to oppose this and other big-government bills that threaten individual liberty and discourage job growth and free enterprise in America. There are three things that you can do to help Richard Morgan win the election:

1. VOTE. Make sure to vote for Richard Morgan in the primary on May 29, 2012. Early voting starts approximately 2 weeks before this. Here is a link to the areas included in Texas’s 21st Congressional District: http://gis1.tlc.state.tx.us/?PlanHeader=PLANC235
2. DONATE. It’s safe to say that most of you reading this do not live in Texas’s 21st Congressional District and therefore cannot vote for Richard Morgan. However, you can help him raise funds to get the message out to those voters that do live in the district. The unique thing about this primary race is that SOPA affects so many more people than just those living within the district Richard Morgan will represent. The ramifications of SOPA transcend local, state and even national boundaries. Anyone, anywhere can donate to Richard Morgan’s congressional campaign and I strongly encourage you to do so. Visit http://richardmorgan.com/contribute/ to make a contribution today!
3. SPREAD THE WORD. Help me get Richard’s message out – accessible here: http://www.richardmorgan.com/issues – to as many people and companies as possible before the May 29, 2012 primary date. The more people and companies that know about this the more visibility his campaign will garner. More visibility will mean increased voter awareness and increased donations. Increased donations will result in increased voter awareness.

   Locations you can direct your friends to:

   Website: http://richardmorgan.com
   Twitter: @Morgan4TX
   LinkedIn: http://www.linkedin.com/in/rickmorgan
   Facebook: https://www.facebook.com/Morgan4TX

Let our voices be heard

Our government is supposed to be for the people, by the people. It is one where every individual voice is supposed to matter and carry with it the ability to instigate change. Help me make those ideals a reality. Please vote. Please donate. And please pass along word of this campaign. Together, united in voice, we can stop SOPA.

svn: Unrecognized URL scheme 'https://svn.web.server'

When I ran svn --version I saw that there was nothing configured to handle the http(s) protocols. To resolve this I did the following:

1. In /usr/ports/www/neon29 I ran make clean install
2. In /usr/ports/devel/subversion I ran make config. From the configuration screen I enabled the Neon WebDAV/Delta-V repo access module and then ran make clean install after saving the configuration.

I was then able to successfully access SVN repositories hosted at http(s) addresses! I hope this helpful to anyone in a similar situation.

Zend Framework…Without Inhaling
Not sure how to integrate all Zend Framework has to offer into your existing code? Do you want to know how you can use Zend Framework without having to fully adopt the MVC architecture? What if you want to begin using MVC later? This article will present ideas and examples on how you can integrate Zend Framework into your existing codebase with minimal need for future refactoring.

The Presentations page has a link to the video recording of the talk, which was very lively with a lot of audience participation. Definitely worth watching!

At the end of the presentation I make reference to an invaluable reference graphic that you owe to yourself to check out. The url for it is http://www.aisee.com/graph_of_the_month/http.png.

REST is a set of principles

If there is one point that you should take away from this post after reading it, it is this: REST is a set of principles and not a specification. Consider for a moment someone you believe to be moral. Traits that may make them moral, such as trustworthiness, decency or honor, are characteristics of their morality; guidelines they follow in their life – a moral code. There is not a law that specifies what morality is, but there is a general sense of what is expected and what is meant when discussing morality. The same holds true for REST. There is not a specific implementation that makes an API RESTful, but instead certain expectations that one should strive to achieve.

The first place you run into “principles versus specification” is with versioning your API. There are really only two ways to implement the concept of versioning in a REST API – either through the syntax of the URI [this also includes using different (sub)domains for different versions] or by the use of HTTP headers. Within the use of HTTP headers, there are two primary options – use of the X-API-Version header or the use of custom media types. But which of these methods are correct? This exact question is discussed several times on the following websites:

• http://www.subbu.org/blog/2009/12/media-types-and-plumbing
• http://barelyenough.org/blog/2008/05/versioning-rest-web-services/
• http://news.ycombinator.com/item?id=1523664
• http://stackoverflow.com/questions/2024600/rest-api-versioning-only-version-the-representation-not-the-resource-itself

After reading these author’s positions, and the ensuing discussions, you are still left with our original question of which method is correct. And there is the “principles versus specification” problem. There isn’t a right or wrong answer about this. There is only opinion and the solution that best serves the needs at hand.

Versioning your REST API

Seeing as that opinion is part of what drives your REST API implementation, and you are reading this blog post, let me take a moment to share with you my opinion on this subject. For me, there are 3 tenets that I have followed in developing my REST API. The two that pertain to versioning are:

1. Do not use custom HTTP headers
2. Do not use custom media types

Why these you ask? For the first one, it is because any proxy that is encountered along the transit path may either modify the headers or strip them off and not deliver them to their intended target. If you are relying on the ‘X-API-Version’ header to specify which version should be used, and it is not present in the request, then what do you do? Revert to the oldest version? Serve the latest? Neither of these are good responses, as what the client gets back cannot be relied on to be consistent. How are they to know whether or not this non-standard header is going to make it to your service or not?

For the second one, I do not believe that versioning of your API is as simple as saying you have a different representation of your data. Sure, if you take a look at the following two examples it’s only about a different representation:

Example 1

<customer>
	<name>Joe</name>
	<phone>555-555-1212</phone>
</customer>

Example 2

<customer>
	<name>Joe</name>
	<phone>
		<home>555-555-1212</home>
		<mobile>555-555-2121</mobile>
	</phone>
</customer>

But what happens when the business logic behind the POSTing to a resource does something different than it did before? The structure of the request, and perhaps even the response, remain the same, but the results of your actions are completely different. This is a version change too. Yes, technically, it’s a change to your application and not the API, but to the consuming client your application is your API. If the behavior of your API changes, even if it is really your application that has, then there is need for a new version of your API.

Do not use custom media types

Using custom media types to represent these types of changes just does not cut it. Custom media types can only be effectively (and questionably at that) used to serve a different representation of the response, but not a different behavior of your application. It is for this reason that I do not use either custom HTTP headers or custom media types and instead specify the API version in the URI. Yes, this is controversial to some but, as we have already established, the other methodologies are likely equally controversial. Heck, this approach even has its own problems for me, as I believe that a URI expresses identity, and identity does not change when a new version is introduced. By using the URI to store the version information we give the visual impression that we are representing different, distinct resources when in fact they are the same identity. But in the battle of “principles versus specification”, wherein the specification (or lack of one) does not give direction on this topic, and my belief in the principle that representing a change to the business logic is more important that representing identity distinctness, this is the solution that I use. You are certainly free to disagree and implement your own solution. The following is an overview of how I manage versioning in my API:

• I version my API with the versioning scheme of [Major].[Minor].[Revision]
• Anything that encompasses a major change to the way the API works results is an increment of the [Major] value. Let’s say that we have version 1.4.7 of our API. We have become successful and just purchased another company. In the process of integrating our two companies together, we have changed some of our fundamental business processes, whereas now how we process payments has completely changed due to new accounting rules, etc. We modify our API and in order to indicate that there have been significant business rule changes, and not just presentational changes, we change the version of our API to 2.0.0.
• Whenever there is a change in the way we interact with a REST resource, we increment the [Minor] value. Again, we start with our API version of 1.4.7. Using our previous examples, Example 1 and Example 2, we change our API version to 1.5.0 after implementing the changes reflected in Example 2.
• The [Revision] value of our API version is incremented whenever we make minor additions to our resources. Using Example 2, let’s say we want to add an additional value in the node to represent a Work number. As long as our change only adds additional data to a resource without making any structure changes, then an increment from version 1.4.7 to 1.4.8 is in need. IMPORTANT: This [Revision] increase is only for when there are no changes to the existing structure! If the consuming application is expecting to find phone numbers under the XML path of “customer > phone” adding an additional one should not cause their code to break (assuming the application is written correctly). However, changing the name of the “Phone” node to “Phones” ABSOLUTELY will cause the the consuming application to break. This is when a [Minor] value change is needed.
• The [Revision] value is not used for bug fixes. Internally on our development team we have our own [Major].[Minor].[Revision] for the API codebase. While it will likely mirror the public API’s version most of the time, the two are not in lock step with one another. Version 1.4.7 of the API, from a consuming application’s viewpoint, is the same when there was a missing bracket in the response and the same after the required bracket was included in the response. The API version represents the business rules of the application and presentational structure of the requests and responses.

This management style results in URIs that look like these, for example:

• https://api.awesomesite.com/v1.4.7/article
• https://api.awesomesite.com/v1.4.7/customer/12/orders

What is involved in maintaining this approach?

Arguably, maintaining the API version in this manner requires a little bit more work. Each version of our API is configured to be hosted as its own application on the server. Our web server of choice is Apache. We use the mod_rewrite engine to set the appropriate ‘DocumentRoot’ value associated with each API version specified in the URI, defaulting to the latest version if the version specified is not recognized. Some of the reasons we do things this way are:

• It allows us to maintain more than one version of our API simultaneously.
• Our code does not become convoluted having to keep track of which version of which resource is supposed to be represented at which time.

Does this mean that for each increment of the [Revision] value we have a new installation of our API application that we install on the server and maintain? Yes. But when you think about this for a moment it’s not as bad as it sounds. Let’s say that we again have version 1.4.7 of our API. When we make a change requiring us to increment to version 1.4.8 we will no longer be making any changes to version 1.4.7. It will sit on the server for whatever amount of time we desire to continue supporting its version. When another change occurs, and we’re at version 1.4.9 of our API, we now have two old versions of the API that we no longer have to make changes to.

How long do you need to keep these old versions of the API lying around? Only you can answer this question, but a decent rule of thumb would seem to be that whenever you increment the [Minor] value you would be safe to remove support for the previous versions. Why you ask? Because if you recall from earlier an increment to the [Minor] value is the result of a change in the way we interact with the REST resource. If we have changed the overall structure of our resource, this seems like a good time to quit supporting previous versions of the structure. Not only does this seem like a good idea, but it will also very likely be necessary.

Another reason this is not as bad as it seems is due to this question: How often are you making changes to your API? Once you have put everything through its paces in development and have had the initial launch of your API how often are you going back to your data representation and adding a mobile phone, for example (and from our previous example)? I ask this question in regards to continuously adding structure to your responses that arguably should have been present from the initial launch. Now if you are feverishly adding new features and capabilities to your API then yes, this can become involved. But how else are you going to maintain it? Whether all the code is maintained in one installation of the application or segregated as I have described it is still code that has to be written. I would rather be adding new API functionality to an isolated instance of the codebase than worry about having to maintain backwards compatibility.

The 3rd tenet

The usage of a REST APi is header-driven. How you intend to interact with the data and business objects is conveyed in the use of GET, POST, PUT and DELETE headers. If you need information about the API endpoints, you use OPTION, TRACE and/or ALLOW. You define the format of your request using Content-Type and specify your desired result format using Accept. But just like I don’t use custom HTTP headers because of concern that proxies may strip them off, how can I guarantee that headers in my response actually make it to the calling application, even if they are all standard and do not use custom headers? Call me paranoid, but you can’t. For that reason, I have a third tenet that I have followed in developing my REST API, which is:

3. Represent the headers in the response payload

Before I show an example of what this looks like, let me provide another reason for taking this step. I am a programmer. As a programmer, I am sometimes developing something that will be consumed and other times I am developing something that is doing the consuming. As the consumptive programmer, I very often run across a situation where I mumble under my breath at the decisions made by the developing programmer in how they arrived at the solution I am attempting to use. Often it is not that more involved to take a few extra steps that will make the life of the consumptive programmer much easier. This third tenant is one such easy extra step. Even if you don’t completely agree with the need for this extra step, or have not yet ran across a situation where it is beneficial, what is really the cost of just doing it anyways? I would proffer that the cost is negligible and that the goodwill earned from your consumptive programmers is worth the effort.

What it all boils down for me is this: I do not know how my API is going to be consumed. Given that REST is a set of principles and not a specification I cannot guarantee that even with the best of intentions that the consuming application will be able to correctly interact with my response headers. Should they be able to access them? Yes. Can they? Who knows. You don’t know if the consuming application is a server-side application written in C# or a browser-based application written in Javascript. Maybe the language or platform the consuming application is written in/on has a limitation of some of the headers not being able to be accessed as desired.

So what does this look like? Consider the following request and response examples:

Request

GET /v1.4.7/countries HTTP/1.1
Host: api.awesomesite.com
Accept: text/xml

Response

Status Code: 200 OK
Date: Wed, 16 Mar 2011 17:31:39 GMT
Vary: Accept
Content-Length: 432
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
	<countries>
		<country>
			<id>1</id>
			<name>United States of America</name>
			<regionCode>US</regionCode>
			<callingPrefix>011</callingPrefix>
			<callingCode>1</callingCode>
		</country>
		<country>
			<id>2</id>
			<name>Canada</name>
			<regionCode>CA</regionCode>
			<callingPrefix>011</callingPrefix>
			<callingCode>1</callingCode>
		</country>
	</countries>
</response>

This is a typical GET request for a resource and the response you would normally receive as a result. Following my third tenant of REST API implementation, you would want to modify your response so that instead it looks like this:

Response

Status Code: 200 OK
Date: Wed, 16 Mar 2011 17:31:39 GMT
Vary: Accept
Content-Length: 512
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
	<headers>
		<ResponseCode>200</ResponseCode>
		<Vary>Accept</Vary>
	</headers>
	<countries>
		<country>
			<id>1</id>
			<name>United States of America</name>
			<regionCode>US</regionCode>
			<callingPrefix>011</callingPrefix>
			<callingCode>1</callingCode>
		</country>
		<country>
			<id>2</id>
			<name>Canada</name>
			<regionCode>CA</regionCode>
			<callingPrefix>011</callingPrefix>
			<callingCode>1</callingCode>
		</country>
	</countries>
</response>

Notice that in this example I have included an additional “headers” node in my response. This is not part of the “countries” node, therefore it’s inclusion or exclusion in the response body will not impact our data being properly represented. What it has done though is ensure that in any situation in which response headers have gotten stripped, or a consuming application is not able to access them, that the header information is still represented. Which headers you choose to include in this node is completely up to you. I have elected to only include those that I deem the most important in maintaining RESTful communication. Concepts and data such as Response Codes and Vary headers are integral parts of RESTful communication – the date and time of the response are not. The reason I do not include the ‘Content-Type’ header and value in the “headers” node is because this header is used to tell the consuming application what format the response body is in. The consuming application will already have to know how to interpret the response in order to be told what format it is in, therefore it is information that is not needed (at the “headers” node level).

Conclusion

I hope that this post has gotten you thinking about some of the decisions you will have to make when developing your REST API and even if you don’t agree with the decisions I have made, you are at least now better prepared to face them. The one thing to remember, above all else, is that REST is a set of principles and not a specification. As long as you document your REST API and applications are capable of consuming it then no matter how you chose to implement it, it was the right way.

Have you been reviewing all Zend Framework has to offer but aren’t sure how to integrate it with your existing code? How can you begin taking advantage of Zend Framework without having to fully adopt the MVC architecture? What do you do when you later want to being using MVC? Hint: You don’t have to throw away any of your code! This session will present ideas and examples on how you can integrate Zend Framework alongside your existing code base with minimal need for future re-factoring.

See all the details on the Presentations page.

UPDATE (17 Aug 2010): Video and code examples have been added to the Presentations page.

I have made the slides and corresponding code examples available for viewing and download on the Presentations page, as well as I recorded the presentation for you to be able to view as well.

I hope this information is useful, and happy coding!

It’s amazing how long it took to write just these six words. I do not mean that it took me an extended amount of time to literally write these six words, but instead am referring to the amount of time it has taken for me to begin blogging. I first gave consideration to the idea of blogging approximately a year-and-a-half ago. Then before I knew it almost that entire time period had passed me by without so much as a single sentence typed. After attending the Dallas, TX stop of the CodeWorks 2009 tour on September 26 and 27, and meeting a venerable list of PHP’s who’s-who, I was once again inspired to begin blogging. But then again, all of the activities of life once again seemingly got in the way. My son had an ear surgery – there went a week. My wife and I attended 30 hours of training to become foster parents – there went, well, 30 hours. A project at work experienced issues – another week gone by. When would I ever finally have time to begin blogging?

I am going to diverge from the previous train of thought for just a moment, but I promise that I will come back around to it in just a moment. I have owned two moderately successful businesses in my past, with one of them having actual real employees who oddly enough required actual real cash dollars every payday. The reason I share this is to say that I am an individual who is not unaccustomed to challenges. In other previous employment endeavors I have been an instructor, both in commercial and educational settings. The reason I share this is to say that I am an individual who is not intimidated by being a resource of knowledge for others. I have been developing with PHP since early 1999 and am a Zend Certified Engineer. The reason I share this is to say that while I am always continuously learning, like all good developers should be, I’ve got solid grasp on the ins and outs of web application development using PHP.

Now here’s where I get both of these trains of thought back together on the same track. Despite having previously faced challenges and enjoy continuously doing so, despite being able to command a classroom with my leadership and despite being an experienced PHP developer that currently leads a team of developers, there is something daunting and somewhat terrifying about the prospect of blogging. It is one thing to start playing with a new piece of technology or software in the privacy of your own office, to implement the tried-and-true “Hello World”, where no one will be aware of how many iterations you had to suffer through before getting right, and it is quite another to do so in full view of the rest of the PHP community and the glaring lights of the not-so-private internet. Please do not misunderstand me. I am not for one moment saying that the PHP community is not one that will welcome a newcomer of any caliber, contributing in any capacity, into its fold. Quite the opposite actually – the PHP community is extremely welcoming with many tremendous members. But what I am saying is that it’s one thing to be judged only by yourself and another to subject yourself to judgment by a multitude of others.

During the five weeks since CodeWorks, when I decided (again) that I was going to begin blogging, I have been going around and around in my head about what my first blog post should be about. I have had several ideas, but was quick to dismiss them as being to ambitious or needing more time that I had at the moment to devote. I finally realized that these were just excuses. The same types of excuses that had kept me from blogging for the past year and more. I was then reminded of two different blog posts I had recently read that spoke, to me, on this subject. While at CodeWorks I had the honor of meeting Chris Cornutt. You should follow him on Twitter: http://twitter.com/enygma. It was two of his blog posts, titled “The Beginner Pattern” (read it here: http://blog.phpdeveloper.org/?p=198) and “Mom Always Said to Share” (read it here: http://blog.phpdeveloper.org/?p=169 that I kept coming back to. Here is what I took from these posts: it does not matter what you are blogging about as long as you are blogging for you. There is not one style that everyone should follow or any one way in which to “correctly” blog. Just as each developer has their own style of coding (within the guidelines of best practices of course), they should also have their own style of blogging. I had allowed myself to become consumed with how I thought my blog posts would be received to the point that I had not even created a single post to be shared. Now I know these exact words are not in either of his posts, and perhaps this exact interpretation was never intended, but this again speaks to my point. Every reader will get something different from my blog posts. It is only my responsibility to be true to myself.

So there it is – my first blog post. What started out as a difficult first six words to write has now turned into over 900 words and counting. For those of you who have stuck with me this whole time and are still reading, I sincerely thank you. If you are an already-established member of the PHP community, likely already with your own blog, I thank you for welcoming me further into the PHP community. If you are someone just starting out I strongly encourage you to jump in with both feet and never look back. As for future posts, I am certain there will be one about my first-time experiences contributing to the Zend Framework, for while I do have a Contributer Licensing Agreement (CLA) on file with Zend, I have somehow always seemed to find something to keep me from ever actually getting around to contributing. As Chris Cornutt says in his post, “Don’t be afraid to put you and your code out there!”

I am now off to shamelessly promote my first post!