Capistrano is a sexy bitch. At least it was until I spent hours trying to figure out how to deploy to multiple servers. Updated Cap, Ruby, compiled Ruby from source twice, etc etc. Capistrano just kept hanging with pushing code to two or more servers at once. Note that I am in Cygwin, if that makes a difference. Also, when deploying with no password on my ssh key, it works…hmm.

Well I added this:

default_run_options[:max_hosts] = 1

To my deploy.rb, and although it now has to deploy to one server at a time, it works. Note that for two servers this is fine. For 200 it’s not so fine. I’ll worry about that when it comes though.

UPDATE!!!! Something I never thought about until now is that you can use ssh-agent to save your keys in memory pre-deploy. Then you have a password-protected key that works with Capistrano WITHOUT doing the max_hosts hack. This is tested (on cygwin) and working for me.

This will be a short post, but pretty cool.

You can add arrays together:

	$test1	=	array('name' => 'andrew');
	$test2	=	array('status' => 'totally gnar, dude');

	print_r($test1 + $test2);
	---------------------------
	Array
	(
	    [name] => andrew
	    [status] => totally gnar, dude
	)

Wow…who would have thought. And my most recent favorite, converting objects to events. It’s a simple foreach($object as $key => $val) and putting each element into a separate array right? WRONG:

	$array	=	(array)$object;

No fucking way. Casting actually works in this case. Why does nobody tell me anything?! This is great for parsing XML because any parser normally returns an object, and quite honestly, I hate dealing with objects. All database data is by default returned as an array usually,  and it’s a pain having some data sources being objects while others are arrays. Now it doesn’t matter…if you like objects, cast an associative array as an (object), if you like arrays cast with (array). I love PHP…

This is the third post (in a row) I’ve made about REST. I’ve now read multiple explanations of REST, many of which say the same thing. Then I see implementations of these explanations, and the people who coined REST turn up their noses. I know someone has implemented REST correctly. I mean, someone out there HAS to have done it right…right? Every criticism of why a service is not RESTful uses terabytes of nit-picking jargon but somehow lacks examples on how that service could be made RESTful.

“This service is NOT RESTful because in REST, payloads are self-describing and contain references to other resources, and servers should be able to change their namespace, and two points always make a line unless one is in hyperspace.” And xyz.com’s REST API wasn’t doing this? What could they have done to change this? What IS REST about their API?

Maybe I’m dumb. Actually, no I’m not. I just can’t look at a spec and say, “Oh, I get it.” I have to see real, live examples. Why can nobody do this? It seems every HTTP “REST” service is a false implementation yet nobody can give a concise explanation of why.

I get that using only GET and POST is not RESTful. I get that every resource is a noun, and has a URL associated with it. I get that verbs are defined by HTTP and should not be used in URLs. I get that HTTP status headers should be used in conjuction with responses. I sort of get what a media type is (application/vnd.ieatmcdonaldstoomuch.cheeseburger) but do not get where it is defined. Or is this arbitrary?

Some points I have taken from all the back-and-forth involved in trying to break into an extremely elitist (and rightfully so, REST is REST) architectural style:

• REST is stateless. All information required to complete the request is sent with the request. Every time.
• REST re-uses existing specs. HTTP has defined some very useful verbs (GET/POST/PUT/DELETE) for us to use. It makes sense to use those instead of creating custom verbage. HTTP also has status headers for letting a client know WTF is happening. 200 OK, 506 Suck My Balls Client, etc.
• REST maps resources to locations. I can find events by doing GET /events. I can post an event by doing POST /events. I can delete an event by doing DELETE /events/123. These URLs (/events, /events/123) are resources…an event collection and a single event. They are abstract things and a description of that thing is what is interacted with (aka “representation”).
• REST uses media types to define resources. I’m assuming this is the “application/vnd.event+xml” content-type thing. This is very confusing for me. Where is this MIME type defined? How is it defined? How does a client consume it? WTF is going on here? Any ideas, anyone?
• A REST service is self-descriptive. Reading one of Roy Fielding’s annoyingly-complex criticisms of bad REST implementations brings up the point that given an initial URL and a “set of standardized media types that are appropriate for the intended audience,” I should be able to completely discover all information on that service. So when I hit the homepage, I should get an XML/JSON/HTML response telling me that there are events under /events? How do I structure this response? What “media type” would this resource be? I get the point behind this, but would love to see a full implementation.

So while I’m have a lot of trouble grasping the last two points, everything else seems to make good sense. So far, anyway. I’m sure in a few minutes I’ll read another guide telling me that everything I know about REST is WRONG and I’m going to hell for even thinking the word REST without knowing exactly what it means.

Perhaps a REST web service that describes how to implement REST over HTTP would be a fun and amusing project…

UPDATE – I suppose a website comprised of HTML that describes REST would be RESTful…no need to make a “service.” Maybe this should be taken under because there seems to be a vague disseration, a few authoritative “resources” who love to use useless jargon, and a collection of blog posts that individually are all wrong, but pieced together create a somewhat workable view of that REST over HTTP should be like. So, someone should definitely get on that. In fact, I just might.

This is a response to a previous post I made about how HTTP authentication is the reason why I’m not building a REST API. After doing a bit more research, I’ve decided that REST is many times better than RPC. Reviewing a lot more information on REST revealed that HTTP authentication is not at all required…but instead a suggested method of authentication only because it’s already built. In fact, any authentication scheme could be cooked up and used. I’ve currently got my eye on OAuth.

That being said, our internal framework is now being updated to support routing different requests to different controllers/actions based on the request method. For instance, I can now route a “POST /events” to /events/add_event, or “GET /events” to /events/get_events. That just about seals the deal on RESTifying the framework, except that I’ll also have to come up with a scheme to implement status headers in the response, either automatically or semi-manually.

There will be no need to do a sort-of REST implementation on the www site. All information needed can be gathered through the API. Gnar, duude.

In conclusion, I’ve decided to go with REST after all. It’s a great architecture, and the best part is that it’s already built for me. Wicked.

So I’ve been in the process of converting beeets.com, which is currently a “website” with integrated back-end code, to a front-end with a back-end API. It’s been an interesting journey, and has spawned a lot of thought recently about how to implement the API.

Obviously, whenever someone says web API, REST is the first this that comes to mind. “Let’s make it a REST API!” From what I’ve been reading about REST (I tend not to use terminology without knowing what the hell it means) many “REST” services aren’t very RESTful (“How I Explained REST to My Wife” – great intro to REST). In fact, the way I’ve implemented the beeets API happens to be closer to RPC. After doing my fair share of research, I’m ok with this.

REST seems like an excellent architecture. In fact, one of the world’s largest global networks is built on that architecture. It works well for what it does…but what the hell does it do? From what I’ve been reading, it gives “resources” (pieces of information) a single location to be accessed/updated/created/deleted. At least this is how it works on the web.

RPC is basically a function or method that runs on a remote machine that can be called by a local machine, completely transparent to the local code. Most RPC implementations work on their own conventions, separately from the beautiful architecture which is REST…what is otherwise known as reinventing the wheel.

So why am I okay with using RPC in the beeets API? The main reason is that RESTful authentication is total junk. It’s great for server-server communication, but NOT so great for user interactions. Users are used to seeing pretty login boxes with “forgot your password? reset it, moron!” or “create an account!” links. Popping up an HTTP login screen is not cool. It’s not cool. This is my main problem with REST.

That being said, if you cannot authenticate REST, then using the built-in methods POST, PUT, DELETE are more or less worthless, unless you have a completely public set of information that anybody can add to, change, or remove…in which case, REST would kick ass.

In light of REST lacking in this area, I think the following makes sense. Create an RPC API that authenticated servers can call to get/create/update/delete information. IPhones, Facebook apps, etc can use this RPC for interacting with the actual dataset. Then on the www front-end, create a REST system that only implements GET.

So I could go to beeets.com/events/123-native-american-slaughter-celebration and get an HTML page with links I can click, an awesome layout, etc. I could go to beeets.com/events/123-native-american-slaughter-celebration.json and get a JSON representation of that event, with URLs to other pages which could be JSON-encoded if need be.

In other words, create a read-only RESTful service on top of the www site, and use an RPC for create/update/delete interactions with the dataset. The already-public information is freely accessibly, without any sort of authentication, so any person or system that cares to consume it can do so. This way you’re still mapping a resource to a location, and providing multiple consumption formats for said resource.

If there is any other way to authenticate users against a RESTful system without an HTTP login, and while being able to control the actual login/registration flow and layout, PLEASE let me know!

UPDATE: please read my followup

So after reading a very good comparison between the two frameworks, I have to say I feel good about my decision to use Mootools in pretty much all of the sites I build. This isn’t because of some nebulous reasoning about Mootools being better than jQuery, but the facts are

• They both do different things, and do them very well
• They intersect in some places (mainly DOM parsing)
• They both have their uses, pros, and cons

I was considering looking into switching beeets.com to use jQuery, but wanted to do some research beforehand. I’m glad I did.

It seems that jQuery is popular because it removes the hassle of doing everyday Javascript chores. Quite frankly, I’ve known Javascript for quite some time, and don’t mind getting my hands dirty in it. So using a framework that abstracts that out and creates what seems like (from reading the syntax) a whole new language makes me groan.

Mootools seems to better extend Javascript itself, and provides the tools to extend it even more. So if you already know JS fairly well, you can look at Mootools code and still tell what’s going on even if you only have an extremely limited knowledge of Mootools. It also implements some great features that allow you to reuse code extremely intelligently. So intelligently, in fact, that in much of the code on beeets.com (JS heavy), we’re actually not tapping into the full power of Mootools. Whoops.

That is another point I wanted to bring up, though. When Mootools 1.11 and earlier was around, things were great. The framework was good, the docs were good, the examples were good. Come 1.2, they changed their site (much uglier), castrated the examples, and the documentation is, in my opinion, pretty jenky. There are no good tutorials on their site, and it seems like there are many features I’ve never tapped into because, well, I just never knew about them.

This is half my fault, half Mootools’. I should be doing my research, but educating those using your framework is a must as well. Let’s hope they work on it, and in the meantime I’ve got some reading to do. It doesn’t help that the update from 1.11 to 1.2 changed an assload of conventions, classes, and method names.

All in all, it seems like Mootools is the way to go if you are already great at Javascript…and I am. That being said, it may be worth me learning jQuery to do simpler DOM parsing and AJAX. For larger projects that actually need to reuse big pieces of code and do more than parse the DOM, I’ll gladly stick to Mootools.

Let the flames begin…

I recently (read: today) had an obnoxious problem: I’m writing some code for creating an ATOM feed, and kept getting errors about entity-escaped values. Namely, things like ’, •, etc. Even written as entities, Opera and IE7 did not recognize them. I read somewhere that it was necessary to convert the named entities to numbered entities. Great.

Well, PHP doesn’t have a native function for this. Why, I do not know…there seems to be functions for many other things, and adding an argument to htmlentities that returns numbered entities would seem easy enough. Either way, I wrote a quick function that takes the htmlentities translation table, adds any missing values that are not in the translation table, and runs the conversion to numbered entities. Check it:

function htmlentities_numbered($string)
{
	$table	=	get_html_translation_table(HTML_ENTITIES);
	$trans	=	array();
	foreach($table as $char => $ent)
	{
		$trans[$ent]	=	'&#'. ord($char) .';';
	}

	$trans['€']	=	'€';
	$trans['‚']	=	'‚';
	$trans['ƒ']	=	'ƒ';
	$trans['„']	=	'„';
	$trans['…']	=	'…';
	$trans['†']	=	'†';
	$trans['‡']	=	'‡';
	$trans['ˆ']	=	'ˆ';
	$trans['‰']	=	'‰';
	$trans['Š']	=	'Š';
	$trans['‹']	=	'‹';
	$trans['Œ']	=	'Œ';
	$trans['‘']	=	'‘';
	$trans['’']	=	'’';
	$trans['“']	=	'“';
	$trans['”']	=	'”';
	$trans['•']	=	'•';
	$trans['–']	=	'–';
	$trans['—']	=	'—';
	$trans['˜']	=	'˜';
	$trans['™']	=	'™';
	$trans['š']	=	'š';
	$trans['›']	=	'›';
	$trans['œ']	=	'œ';
	$trans['Ÿ']	=	'Ÿ';

	$string	=	strtr($string, $trans);
	return $string;
}

Hope it’s helpful.

UPDATE – apparently, even the numbered entities are not valid XML. Fair enough, I’ve converted them all to unicode (0×80 – 0x9F). All my ATOM feeds validate now (through feedvalidator.org).