My son Sam stole my balance today!
I had squatted down on the balls of my feet this morning to give Sam a hug, and he leaned towards me enough that I started falling over backwards. Sam on weighs about 40 pounds, but it took very little pressure from him to almost totally unbalance me: I was practically on my toes already and in a very precarious position.
If you’re unfamiliar with the concept, balance stealing is a tactic used in Aikido and Bagua Zhang (and other arts as well, I’m sure) to subtly get your opponent off balance and then do terrible things to them. I find a nice applications demo on Youtube that illustrates the application here (requires Flash, sorry).
I felt pretty conflicted at that moment, because morning hugs are a big deal in our house, and I let the kids hug me until they feel like they’ve had enough. I work a lot and I want my time with the kids to count, so telling him that he had to stop was unappealing.
Fortunately, we were in the kitchen, and our kitchen island (which is on wheels) was just within reach. I reached out and hooked a single finger behind one of the table legs and the problem was solved.
All of this illustrates the beauty and power of balance stealing: I could cancel out the force he was exerting on me with one finger, but without that stabilizing force, I was helpless.
One of the apps we’re writing for our customer requires the ability to upload videos to Vimeo, so I got the chance to work with their web services APIs this weekend. There aren’t any publicly available Objective C classes for this, so I ended up rolling my own.
Unfortunately, this ended up being an exercise in the value of good documentation. Here’s what I found.
The Upload Process
The real problem was in step 3: “Post the Video Files.” This step didn’t work, and I spent about 20 hours altogether, with considerable help from my friend and business partner George, trying to figure out what was going on.
Here’s what the Vimeo Upload API site currently has to say:
So, right off the bat, we have to do some special things around authentication. Okay, we’ll keep that in mind if anything goes wrong. This is a POST transaction, so the parameters probably need to go in the POST body.
So we try it, and get a response of “415 – media format not supported.”
The problem here is that it’s a guessing game: we have been given the rules but haven’t actually been given any clear guidelines about where the parameters are supposed to be and what format the video is supposed to be in (I’m talking about upload format, not video codec format).
Eventually we started using a multipart MIME format for the document, which got us past the 415 response code. The entirety of the new error message was:
Upload failed. try again!
No error code, no explanation. Nothing.
The biggest red flag, to my mind, was the signature. The API documentation had gone out of its way to emphasize the importance of getting the signature parameters right, so this is where we looked first.
After several hours we learned: * A hell of a lot about OAuth signature generation * A hell of a lot about Google’s OAuth code * That GData OAuth only uses URL parameters for generating a signature. It does not look at the body at all.
Eventually I realized that there was too much ambiguity about where the service was expecting to find the parameters, so I downloaded Vimeo’s desktop uploader (an Adobe AIR app), and started looking at call traces with Wireshark. This was a lifesaver:
- The Vimeo app doesn’t sign its own uploads
- There was a missing parameter in the API documentation (“filename”).
Once I added the filename attribute the upload worked on the first try. I was able to verify that I could upload chunks with or without authenticating the upload chunk request before sending it.
The winning combination
So, what worked for us was to do a POST, as the document indicates, with the ticket_id and chunk_id as URL parameters, and with the FileName and file_data parameters as multipart form data, followed by the actual chunk data, with a content type of video/quicktime.
At first I thought of the Vimeo documentation as a few tantalizing clues to help you solve the uploading puzzle, but now I consider it to be openly malicious documentation. You would actually be better off without it because they withhold information critical to your success while simultaneously throwing a gigantic red herring at you.
I don’t know why Vimeo states that they require this step to be authenticated, nor why they have stated so explicitly how the signature has to be constructed for this particular call. Perhaps they had to relax the requirement internally and didn’t update their documentation. What I do know is that it steered me in a completely different direction than I needed to go in.
Likewise, the response messages from the upload server are almost criminally opaque. If a parameter is missing, it would be helpful to indicate that in the error message. Most of the other error and status messages Vimeo provides are detailed and articulate.
Finally, the omission of the Filename parameter itself from the API documentation, which is mandatory for the upload to succeed, sucked. In retrospect, this is a standard part of the Content-Disposition field and probably would have been included anyway if we’d started out on this with directions appropriate for doing a low-level implementation of the protocol.
In any case, if you are looking to do Vimeo uploading in native code, the bottom line is: use multipart-mime with a content disposition block for the actual binary data. Authentication for this particular call appears to be disabled, but could come back at any time. For now, if you’re having problems with uploading, it’s probably due to your message format and not your signature.
One distinguishing characteristic of the internal martial arts is their approach to power generation, although many of the techniques studied are present in one form or another. The Neijia stand out in that much of their focus that they consciously strive to generate power through practiced execution of refined physical techniques instead of reliance on raw muscular force.
### Use of the ground
One of the simplest ways to generate power is by pushing off of the ground with the legs while (essentially) stiffening the arm you wish to extend the force through.
From a static analysis point of view, this is nearly identical to the classic stiff arm/straight arm/”don’t bother” maneuver found in American football and rugby.
In this technique, the player isn’t punching and they aren’t exercising a tremendous amount of localized strength. They are instead using their own skeletal frame and tendons to form a rigid structure that channels the incoming player’s momentum through the outstretched arm and into the ground. To the attacker, this is like crashing into a brick wall.
In this application, the attacker’s momentum is used against them. But by learning to close the joints of the legs, hips, and arms and rapidly expanding them, a skilled practitioner can use the ground in the same way to generate power in their techniques. No upper body strength is used, but the same extensive power is pushed off the the ground and into (or if you’re nice, through) the opponent’s body.
Here’s one of my favorite clips of someone using the ground to throw their students around. Some of the students appear to be “helping” (bouncing or skipping excessively in sympathy with the movement – this is the martial art student’s way of being a suck up) but a much of the student tossing is genuine.
If you watch closely you can see the ripple of power going up through the instructor’s legs and torso and out through his arms and hands.
Out of time. More later!
So, it looks like my last post was over a year ago.
Life is funny, in that, when things are the busiest, it’s hard to stop and talk about it.
The last year has been very busy, and great. My company, Black Pixel has taken off. My daughter Eleanor was born and just had her first birthday. Between work and the new baby, things like blogging and kung fu fell off the table for awhile.
I also played with Tumblr for awhile, but I’m not sure it’s really my cup of tea, particularly in light of the number of outages they have had recently.
Anyway, more blog posts to come. I have a lot to share.