Comment on the SmugMug 2.0 API

A post I put on the SmugMug forum, called Digital Grin:

I just converted my app SmugMugBrowser to the 2.0 API, and the result is OK, even an improvement in performance, because I can now access the folder/album hierarchy level-by-level. Before, I had to retrieve all the albums and then compute the hierarchy from the categories and subcategories. So, that part is good.

But the documentation is terrible. Someone, perhaps several people, think that the live API screens are a replacement for documentation, but they are wrong. Not that the live screens aren’t useful, but they are not documentation.

As a result, I’m forced to do a lot of guesswork and run a lot of experiments to determine the rules. This is silly! The rules should be stated explicitly.

For example, I determined that I could pass a “count” parameter when I’m getting nodes, but nowhere that I can see is this documented. There were lots of little examples like that. As a result, my work took longer, was frustrating, and may not be using the API in the best way.

Here’s a question I can’t answer: Is there a replacement for the CustomSize parameter that is in the 1.3 API? (I know that I can construct a custom-size URL–this is different.) I have a lot of questions like that. What parameters can I use to speed things up or produce a better app? No idea.

If SmugMug wants to continue to progress with apps and websites that work with it, it will have to do much better. This on-the-cheap approach just isn’t good enough.

SmugMug isn’t alone here–I see this lack of documentation all over, because API providers know they can get away from it. But it’s stupid: If you want developers, and every platform company does, why make it so difficult? In my experience, the best API documentation ever, by a wide margin, comes from Apple. SmugMug goes in that group at the bottom, the very worst.

This is only about the documentation. Near as I can tell, SmugMug’s API itself is really well implemented, and I didn’t find any bugs, either. No one is saying they’re not good programmers.