Comment on the 2.0 API

Marc Rochkind

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.

gabbie

Hi Marc,

Thank you for taking the time to leave us feedback on our documentation. You raise a lot of great points and I'm hoping to work with our API team to improve our documentation to include more of the type of information that you're describing here. We do have some articles with that type of information under our Advanced Topics, but there's plenty more nuances that should be documented. In the mean time, we're happy to answer questions as you come to them, either here on the dgrin forum or via email.

As to your question about the CustomSize parameter, have you seen our custom size endpoint in API 2.0? https://www.smugmug.com/api/v2/image/:imagekey:!sizecustom
Does that work for your use case?

Marc Rochkind

Thanks for getting back to me. I don't think the custom size endpoint does what I want, as I always retrieve all the images in an album at once, and the 1.3.0 API allowed me to request that a custom-size URL be supplied for each one. This isn't a big deal at all in my application, as I just form the custom-size URL in my code. My point wasn't that I needed the CustomSize parameter, it was that it was too difficult to determine whether the parameter was available.

In other words, my complaints are only about the documentation, not about the API itself.

As for articles, tutorials, examples, videos, forum topics, and things like that: They are all good to have, but the most important thing to have first is authoritative reference documentation. That's what's missing!