smugmug.albums.get and more levels of hierarchy in the future?

jfriend

I plan to use smugmug.albums.get to display a site index and I'd like to write the JS code in a way that won't have to be changed when Smugmug starts supporting more levels of hierarchy than just categories and subcategories. Is there any way to do that?

As of now, the response looks like this which specifically calls out Category and SubCategory which doesn't look to me very extensible to additional levels of hierarchy:

{
  "stat": "ok",
  "method": "smugmug.albums.get",
  "Albums": [
    {
      "id": 5608869,
      "Key": "vwzCG",
      "Category": {
        "id": 315305,
        "Name": "Kenya",
        "URL": "http://jfriend.smugmug.com/Kenya"
      },
      "SubCategory": {
        "id": 568323,
        "Name": "Highlights",
        "URL": "http://jfriend.smugmug.com/Kenya/Highlights"
      },
      "Title": "Landscapes",
      "URL": "http://jfriend.smugmug.com/Kenya/Highlights/Landscapes/5608869_vwzCG"
    },
    {
      "id": 5608779,
      "Key": "ZJ27n",
      "Category": {
        "id": 315305,
        "Name": "Kenya",
        "URL": "http://jfriend.smugmug.com/Kenya"
      },
      "SubCategory": {
        "id": 568323,
        "Name": "Highlights",
        "URL": "http://jfriend.smugmug.com/Kenya/Highlights"
      },
      "Title": "Animals",
      "URL": "http://jfriend.smugmug.com/Kenya/Highlights/Animals/5608779_ZJ27n"
    },
...

Is there any way to write forward looking code that won't have to be rewritten when more levels of hierarchy are supported? Is this part of the API going to be revamped ahead of the launch of more levels of hierarchy so code can prepare?

MSkaffari

At the moment we don't have a method in the API to predict the future Once we move to more levels the APIs will change and you have to adjust your implementation also. We'll do our best to make the transition as easy as possible.

We are working on a setup that enables you to receive info and access to upcoming changes some time before full launch. Follow the forum for more info.

jfriend

MSkaffari wrote: »

At the moment we don't have a method in the API to predict the future Once we move to more levels the APIs will change and you have to adjust your implementation also. We'll do our best to make the transition as easy as possible.

We are working on a setup that enables you to receive info and access to upcoming changes some time before full launch. Follow the forum for more info.

You could design the new method and release a version of that even though there are only two levels now. That would be the forward thinking way of doing things. There is no need to predict the future, all you have to do is design a response format that works with more than two levels.

So, if I understand what you're saying, this method will break in the future when you release more levels. Bummer, that's unfortunate to have to design code now that you already know will break in the future. The fact that you're working on more levels of hierarchy has been known for a long time - I'm surprised the API isn't out in front of that to keep newly written code from breaking in the future.

SamirD

jfriend wrote: »

I'm surprised the API isn't out in front of that to keep newly written code from breaking in the future.

From what I've gathered, the API is a bit of an afterthought at times. The stats still don't work from the API--that's been broken for years now.

devbobo

jfriend wrote: »

So, if I understand what you're saying, this method will break in the future when you release more levels. Bummer, that's unfortunate to have to design code now that you already know will break in the future. The fact that you're working on more levels of hierarchy has been known for a long time - I'm surprised the API isn't out in front of that to keep newly written code from breaking in the future.

John,

No, that is not correct. When we release more levels of hierarchy, we will be releasing a new api version which will support the new hierarchy scheme. The old api versions will continue to work with the existing cat/subcat restrictions (for a period of time to give developers a chance to migrate).

Cheers,

David

jfriend

devbobo wrote: »

John,

No, that is not correct. When we release more levels of hierarchy, we will be releasing a new api version which will support the new hierarchy scheme. The old api versions will continue to work with the existing cat/subcat restrictions.

Cheers,

David

But, how will a gallery at a third level of hierarchy be represented in the existing API response? Will it just be missing? Or not show correct level? Either way, my site index will be wrong and my code will have to be rewritten. I'm just trying to avoid having to write code now that will be broken in the future.

Why not release a new response format now that lets developers code for both the present and the future rather than making us write one way now and have to rewrite in the future?

devbobo

jfriend wrote: »

But, how will a gallery at a third level of hierarchy be represented in the existing API response? Will it just be missing? Or not show correct level?

Why not release a new response format now that lets developers code for the future rather than making us write one way now and have to rewrite in the future?

From an api perspective, not all of the specifics has been bedded down yet. As you mentioned in your original post, the current method isn't very extensible.

Currently hierarchy-wise, you defined a CategoryID and SubCategoryID for an album. For the new format, these parameters will most probably be replaced by a ContainerID or ParentID, rather than adding a third parameter like SubSubCategoryID.

I haven't determined yet how practical (or efficient) it will be to return the entire hierarchy for every album in the smugmug.albums.get response.

Off the top of my head, one possible response format could be as below, where we just return the immediate parent (note, for ease of a sample, I used CategoryID as the ContainerID...that won't be the case in reality)

{
  "stat": "ok",
  "method": "smugmug.albums.get",
  "Albums": [
    {
      "id": 5608869,
      "Key": "vwzCG",
      "Container": {
        "id": 315305,
        "Name": "Kenya",
        "URL": "http://jfriend.smugmug.com/Kenya"
      },
      "Title": "Landscapes",
      "URL": "http://jfriend.smugmug.com/Kenya/Highlights/Landscapes/5608869_vwzCG"
    },
    {
      "id": 5608779,
      "Key": "ZJ27n",
      "Container": {
        "id": 315305,
        "Name": "Kenya",
        "URL": "http://jfriend.smugmug.com/Kenya"
      },
      "Title": "Animals",
      "URL": "http://jfriend.smugmug.com/Kenya/Highlights/Animals/5608779_ZJ27n"
    },
...

As for backwards compatibility with older api methods, we haven't yet determined whether albums in a deeper level of hierarchy would be returned with a truncated hierarchy (cat/subcat only) or excluded from the response altogether.

Hope that makes some sense.

Cheers,

David

jfriend

devbobo wrote: »

From an api perspective, not all of the specifics has been bedded down yet. As you mentioned in your original post, the current method isn't very extensible.

Currently hierarchy-wise, you defined a CategoryID and SubCategoryID for an album. For the new format, these parameters will most probably be replaced by a ContainerID or ParentID, rather than adding a third parameter like SubSubCategoryID.

I haven't determined yet how practical (or efficient) it will be to return the entire hierarchy for every album in the smugmug.albums.get response.

Off the top of my head, one possible response format could be as below, where we just return the immediate parent (note, for ease of a sample, I used CategoryID as the ContainerID...that won't be the case in reality)

{
  "stat": "ok",
  "method": "smugmug.albums.get",
  "Albums": [
    {
      "id": 5608869,
      "Key": "vwzCG",
      "Container": {
        "id": 315305,
        "Name": "Kenya",
        "URL": "http://jfriend.smugmug.com/Kenya"
      },
      "Title": "Landscapes",
      "URL": "http://jfriend.smugmug.com/Kenya/Highlights/Landscapes/5608869_vwzCG"
    },
    {
      "id": 5608779,
      "Key": "ZJ27n",
      "Container": {
        "id": 315305,
        "Name": "Kenya",
        "URL": "http://jfriend.smugmug.com/Kenya"
      },
      "Title": "Animals",
      "URL": "http://jfriend.smugmug.com/Kenya/Highlights/Animals/5608779_ZJ27n"
    },
...

As for backwards compatibility with older api methods, we haven't yet determined whether albums in a deeper level of hierarchy would be returned with a truncated hierarchy (cat/subcat only) or excluded from the response altogether.

Hope that makes some sense.

Cheers,

David

Either way, my code will not perform correctly as would be true with any other code representing a gallery hierarchy. I'd strongly suggest you put out a new response option soon (long before the additional hierarchy is actually released) so people can write code that will not have to be rewritten or have lots of time to adapt previously written code.

I guess I'm being a pain about this because I HATE writing code that I know will have to be rewritten in the future. It violates one of my principles of quality software development.

devbobo

jfriend wrote: »

Either way, my code will not perform correctly as would be true with any other code representing a gallery hierarchy. I'd strongly suggest you put out a new response option soon (long before the additional hierarchy is actually released) so people can write code that will not have to be rewritten or have lots of time to adapt previously written code.

umm, no that's not correct either...the new response format will be rolled out on a new api version (ie. most likely 1.4.0), so your code will function exactly as it does now on whatever api version you are currently using, until you upgrade to that version and modify your code accordingly.

jfriend

devbobo wrote: »

umm, no that's not correct either...the new response format will be rolled out on a new api version (ie. most likely 1.4.0), so your code will function exactly as it does now on whatever api version you are currently using, until you upgrade to that version and modify your code accordingly.

You don't seem to understand my point. When customers start using four levels of hierarchy, the existing smugmug.albums.get method will just be wrong because it isn't capable of representing four levels of hieararchy in it's response. Sure, the method on a pre-existing version of the API will continue to function, but it will have incomplete data - thus people using it on sites that have used more than two levels of hierarchy will get incomplete data and wrong results. Code written to the existing API that is displaying a gallery hierarchy on sites that have started to use the new levels of hierarchy will not show a correct hierarchy.

If you introduced a new response format that can represent the additional levels of hierarchy now, then people could write code once that would work with the existing two levels now and the additional levels of the future - no rewrite needed.

devbobo

sure, I get your point...but I'm sure that people implementing your code on their site, won't have a problem with upgrading to a new version to get more levels of hierarchy.

jfriend

devbobo wrote: »

sure, I get your point...but I'm sure that people implementing your code on their site, won't have a problem with upgrading to a new version to get more levels of hierarchy.

Easy for you to say. A LOT of people who implement my customizations completely forget how the customization was ever installed and do not follow the forum regularly so the only way they find out that a new version is needed is that they notice their site is not working properly or someone tells them their site isn't working and then they have to post to ask how to fix it.

That's not the best way for anyone and it's a lot of extra work for me to support. I'd prefer not to have to put anyone through that (including all the extra work for me to support them). The fact that customizations can regularly break on Smugmug is one of the things that makes it a pain to have a highly customized site on Smugmug. I'm trying to champion there being less breakage, both selfishly for my own support burden, because people using customizations will have better sites and less maintenance and because it makes a better service overall for you.

devbobo

sorry John, but your constant referral to breakage is just wrong. As I have explained above, the current APIs will return Category and SubCategory info as they have always done and your code will continue to work as it does today.

Nothing is remotely broken there.

jfriend

devbobo wrote: »

sorry John, but your constant referral to breakage is just wrong. As I have explained above, the current APIs will return Category and SubCategory info as they have always done and your code will continue to work as it does today.

Nothing is remotely broken there.

I'm guess I'm surprised you don't see the benefit now of releasing an API response that will show the future N levels of hierarchy.

Take the example of a customer who installs this customization now to show a hierarchical site index on their site. Then you release N levels of hieararchy and they modify their site to use more levels. Then, ask that customer if their site index is functioning correctly. They will say "No" - it's not working correctly (broken).

You can argue a technicality whether it's the API function that's broken or not - the point is what the customer sees/feels and their functionality will be broken. That's what I'm trying to avoid and I'm surprised you don't seem interested in helping. I can't believe that you don't see the value in releasing an API response now that can be written to once and will work 100% correctly both now AND after N levels of hierarchy are released. If you don't understand that value to your API consumers, then there's not much I can do here as it's a pretty basic feature of a quality API (it continues to deliver complete results even as new features are added and doesn't have to be recoded by people using it).

If you don't care to see my point here, I guess I'll be done now and SM customers will just have to deal with customizations that require maintenance in the future (what I'm trying to avoid).

SamirD

jfriend wrote: »

Easy for you to say. A LOT of people who implement my customizations completely forget how the customization was ever installed and do not follow the forum regularly so the only way they find out that a new version is needed is that they notice their site is not working properly or someone tells them their site isn't working and then they have to post to ask how to fix it.

That's not the best way for anyone and it's a lot of extra work for me to support. I'd prefer not to have to put anyone through that (including all the extra work for me to support them). The fact that customizations can regularly break on Smugmug is one of the things that makes it a pain to have a highly customized site on Smugmug. I'm trying to champion there being less breakage, both selfishly for my own support burden, because people using customizations will have better sites and less maintenance and because it makes a better service overall for you.

I completely agree with John on this. He spends A LOT of time supporting SM customers as well as being one, and disregarding his concerns is pretty ungrateful. Maybe the implementation would be completely different, but his points are very, very valid.

devbobo

SamirD wrote: »

I completely agree with John on this. He spends A LOT of time supporting SM customers as well as being one, and disregarding his concerns is pretty ungrateful. Maybe the implementation would be completely different, but his points are very, very valid.

I'm not sure how outlining the facts is being ungrateful.

SamirD

devbobo wrote: »

I'm not sure how outlining the facts is being ungrateful.

Because you have the power to change the facts, and didn't express much of an interest in even accomodating his request.

Andy

Hi John, we try to keep the API updated as quickly as possible, and allow you the flexibility you need. We hear your concerns, and thank you for the passionate posts and feedback. This is really valuable to us and Devbobo and Miikka are taking your feedback. Thanks.

Andy

SamirD wrote: »

Because you have the power to change the facts, and didn't express much of an interest in even accomodating his request.

Samir, Devbobo works full time on the API for us and the feedback John has given is invaluable.

SamirD

Andy wrote: »

Samir, Devbobo works full time on the API for us and the feedback John has given is invaluable.

I'm glad to hear it. Just remember that actions speak louder than words.

Andy

SamirD wrote: »

I'm glad to hear it. Just remember that actions speak louder than words.

For a long, long time, we've devoted a TREMENDOUS amount of $$$$$ and human resource into our API, and have fostered many, many, many apps from it.

SamirD

Andy wrote: »

For a long, long time, we've devoted a TREMENDOUS amount of $$$$$ and human resource into our API, and have fostered many, many, many apps from it.

I know that. I'm just saying that actions speak louder than words.

The stats API is still broken, btw. :cry

jfriend

Andy wrote: »

Hi John, we try to keep the API updated as quickly as possible, and allow you the flexibility you need. We hear your concerns, and thank you for the passionate posts and feedback. This is really valuable to us and Devbobo and Miikka are taking your feedback. Thanks.

I guess I'll sum up my contribution here by saying that this was such a strange thread. All I was looking for someone from Smugmug to do was to say that they understood why it would be useful to have a new response format out for the API method smugmug.albums.get (or some new method if desired) as soon as possible so developers could write code once now that would not have to be redone after N levels of hierarchy comes out. Though I think I explained the logic, I never really got that specific acknowledgement. In fact, it was suggested to me that people using my customizations wouldn't have any trouble updating to a new version of the customization in the future (which is the opposite of my point and is exactly what I'm trying to avoid).

I suspect that devbobo and I just don't communicate well on the forums here because I know he's acted on previous suggestions I've made in the last few months: session-less API access that works when site is in read-only mode is in 1.3 and custom size option that makes it easier to deal with new image URLs is also in 1.3. So, it seems like the spirit is willing and hopefully we just have a communication glitch on this issue.

So, I hope my point was clear enough to be understood and the API will be modified to support N levels long before N levels actually ships (as soon as possible would be best).

Meanwhile, I guess that I have no other choice now but to write code that uses the current (old) format of the API that will have to be modified later to support N levels. That's what I was hoping to avoid.

MSkaffari

Yes John.

We understand your desire and need to have any new response format or API available before our customers have access to deeper hierarchies.

What I was trying to say is that we don't have it at the moment. So if you build something NOW we unfortunately can't tell you how to make it future proof since we don't have full design or implementation for those APIs.

I'm also saying that we will make this available as soon as we can, and definitely before our customers have access to the functionality.

jfriend

MSkaffari wrote: »

Yes John.

We understand your desire and need to have any new response format or API available before our customers have access to deeper hierarchies.

What I was trying to say is that we don't have it at the moment. So if you build something NOW we unfortunately can't tell you how to make it future proof since we don't have full design or implementation for those APIs.

I'm also saying that we will make this available as soon as we can, and definitely before our customers have access to the functionality.

Great. Thanks. Sooner would be better for your developers.