Using the Azure SDK for PHP - What I learned
I have been using an SDK for Windows Azure in PHP for some time. We run a cloud system and it stores images on Azure blob storage. A web service retrieves these and returns them in API calls. This all worked fine but then I got hit by the dreaded update.
This is what I learned.
Update problems affect all companies I have ever seen who produce APIs but it will affect larger companies like Microsoft much more so.
A normal update to the same API with a new version number is mostly OK because if the worst happens, you simply downgrade and carry on (hopefully). This update however was not normal, it is a polar shift in the SDK, which involves moving the source, changing its name, listing it on Packagist for a Composer install and the whole 9 yards.
I learned firstly that when this happens, many code snippets, blog posts and forum answers are immediately useless but are not obviously useless because they are still called "Azure SDK", "PHP SDK" etc. If the team called it something more specific or gave it a much more specific version, you could tag posts with version numbers (hey Google, how about adding this to your search engine?).
What I also learned is that when this happens, everything can change. Now this would actually be OK if literally everything changed but of course, it doesn't all change. It's still for Azure, it's still called an SDK and it still provides more or less the same functionality but then it gets weird. We now use namespaces (which is nice) but all the classes have now changed. I no longer have some weird long name class to represent a blob but instead a name-spaced class. This would be OK but even the operation has now changed - arguably to a better model but a big change nonetheless. I no longer create a "blob" object and call getBlobData as before. Instead, I create a blob service proxy and call getBlob on the proxy. I can no longer simply echo the result of getBlobData back to the user but have to use fpassthru and pass it $result->getContentStream().
Of course, what I quickly learned is that the documentation, as usual, is pretty much the 80% of the 80/20 rule. In other words, the easy documentation that I can guess is mostly there but the important stuff like how to port my old code to my new is missing (where is the blobExists() function?), how do I get a Blob? A few rough examples but nothing that useful. Why doesn't every method have an example in the docs (even a simple one)? Why is it that if I set the prefix of listBlobs to "something" then it finds "something.png" but if I set the prefix to "something.png", it doesn't despite the documentation that says, "will return all objects whose names start with the prefix". Why don't the automatic properties work properly (to be fair that might be my local version of PHP but why not add it to my rants?)
The one that really made my head explode was getting a very nice API error from Azure when calling listBlobs (or in fact most of the other methods I tried) saying words to the effect that the MAC signature of the request is incorrect (I understand what that means but not why). I am not calculating the MAC (and thank goodness, since in some languages you have to and I would have wasted my time chasing my tail). The problem? I had mistakenly put a space in my queried container name ("uploaded files" instead of "uploadedfiles") and spaces are not permitted in container names, which is fine, although a nicer exception would have been useful!
So that's when I learned that even companies like Microsoft with all their experience and feedback over the years still cannot capture a large enough number of failure cases and provide useful information to the user. Guess how long it would have taken me if the exception was "invalid container name"?
Don't get me started on their new online licensing. I wasted another 4 hours today trying to work out why my colleague couldn't licence his copy of Visual Studio, despite dashing between MSDN, Bizspark, microsoft.com, azure, visualstudio.com, 50 similar but slightly different login screens and the subtle but very unhelpful message "Downloaded licence insufficient". Eventually, it all percolated through so hey Microsoft, what about a message saying, "update in progress, try again later"?
This is what I learned.
Update problems affect all companies I have ever seen who produce APIs but it will affect larger companies like Microsoft much more so.
A normal update to the same API with a new version number is mostly OK because if the worst happens, you simply downgrade and carry on (hopefully). This update however was not normal, it is a polar shift in the SDK, which involves moving the source, changing its name, listing it on Packagist for a Composer install and the whole 9 yards.
I learned firstly that when this happens, many code snippets, blog posts and forum answers are immediately useless but are not obviously useless because they are still called "Azure SDK", "PHP SDK" etc. If the team called it something more specific or gave it a much more specific version, you could tag posts with version numbers (hey Google, how about adding this to your search engine?).
What I also learned is that when this happens, everything can change. Now this would actually be OK if literally everything changed but of course, it doesn't all change. It's still for Azure, it's still called an SDK and it still provides more or less the same functionality but then it gets weird. We now use namespaces (which is nice) but all the classes have now changed. I no longer have some weird long name class to represent a blob but instead a name-spaced class. This would be OK but even the operation has now changed - arguably to a better model but a big change nonetheless. I no longer create a "blob" object and call getBlobData as before. Instead, I create a blob service proxy and call getBlob on the proxy. I can no longer simply echo the result of getBlobData back to the user but have to use fpassthru and pass it $result->getContentStream().
Of course, what I quickly learned is that the documentation, as usual, is pretty much the 80% of the 80/20 rule. In other words, the easy documentation that I can guess is mostly there but the important stuff like how to port my old code to my new is missing (where is the blobExists() function?), how do I get a Blob? A few rough examples but nothing that useful. Why doesn't every method have an example in the docs (even a simple one)? Why is it that if I set the prefix of listBlobs to "something" then it finds "something.png" but if I set the prefix to "something.png", it doesn't despite the documentation that says, "will return all objects whose names start with the prefix". Why don't the automatic properties work properly (to be fair that might be my local version of PHP but why not add it to my rants?)
The one that really made my head explode was getting a very nice API error from Azure when calling listBlobs (or in fact most of the other methods I tried) saying words to the effect that the MAC signature of the request is incorrect (I understand what that means but not why). I am not calculating the MAC (and thank goodness, since in some languages you have to and I would have wasted my time chasing my tail). The problem? I had mistakenly put a space in my queried container name ("uploaded files" instead of "uploadedfiles") and spaces are not permitted in container names, which is fine, although a nicer exception would have been useful!
So that's when I learned that even companies like Microsoft with all their experience and feedback over the years still cannot capture a large enough number of failure cases and provide useful information to the user. Guess how long it would have taken me if the exception was "invalid container name"?
Don't get me started on their new online licensing. I wasted another 4 hours today trying to work out why my colleague couldn't licence his copy of Visual Studio, despite dashing between MSDN, Bizspark, microsoft.com, azure, visualstudio.com, 50 similar but slightly different login screens and the subtle but very unhelpful message "Downloaded licence insufficient". Eventually, it all percolated through so hey Microsoft, what about a message saying, "update in progress, try again later"?