Announcing: SmugMug Java API

[rkalla]

Update #1: [12-13-07] Beta 2 Released!

Update #2: [03-08-08] Beta 3 Released!

Update #3: [03-08-08] Beta 4 Released!

I'd like to announce the Beta 1 release of the kallasoft SmugMug Java API

For the quick-clickers in the group, here are the links:
[Download] [Javadoc] [Manual] [Announcement] [Homepage]


For the folks still reading, this Beta 1 release represents full coverage of the SmugMug JSON API v1.2.0 as well as some of the binary-only communication methods (HTTP Put supported now, will add support for replacing an image soon).

The simple examples page may give you a better idea of how to use the API out of the gate (I will be adding more examples and demo applications soon). Also for the folks that want to know exactly what is going on behind the scenes, the Manual includes complete coverage of Request/Reply pairs for each API version that is supported (v1.2.0 here).

The purpose of the API is to make developing Java applications against the SmugMug service a walk in the park. The goal is to allow you to focus on your application and not worry about things like JSON object parsing, HTTP requests, headers, response streams and all those details.

The API is developed and released under the Apache License v2.0. The goal was to allow the broadest audience to make use of the API with the only requirement of the license being proper credits given back to the project (hopefully not a show-stopper for anyone). Take the code, examine it, use it and make some cool apps!

Any bugs you find, feedback or just general comments are welcome and encouraged either here in this announcement or in the API's official forums. I'll try and do a good job of consolidating feedback if things get too split up.

I'd also like to know the folks out there developing applications with the API. If you wouldn't mind stopping by and dropping a note in the "List Your Applications!" forum, that would be much appreciated. For the folks that are developing an app but don't have a web prescence for it yet, you could post a screenshot or some details about your app, I'm sure a lot of folks would be interested.

I hope this proves to be valuable for the community now and as it continues to grow to include the awesome work David and the Smug team is doing on the 1.2.1 API (which looks really big )

[onethumb]

Wow, this is so cool! Thanks!!

I'll find a spot to link it on the Wiki, announce it on the API list, and our blog.

Thanks again!

[rkalla]

Originally Posted by onethumb

Wow, this is so cool! Thanks!!

I'll find a spot to link it on the Wiki, announce it on the API list, and our blog.

Thanks again!

Wow, thank you! The support is much appreciated!

[flyingdutchie]

This is a nice library you wrote!

I would suggest you build another library on top of this. Your current library is rather method/action focused, not so much object focused.

I would like to be able to code something like these snippets below:

Map<Album> albums = Albums.retrieveAll(true); // calls (albums.get)

Album album = albums.get(albumID); // if not loaded calls (albums.getInfo)
album.setName(textField1.getText());
album.setDescription(textField2.getText());
...
...
album.update(); // calls (albums.changeSettings).

Album album = albums.get(albumID);
Map<Image> images = album.getImages(); // calls (images.get)

Album album;
album = ....;
...
Image image = album.getImage(imageID); // if needed calls (images.getInfo) and caches image into album.
image.setComment("some comment");
image.setKeywords(new String[] {"keyword1","keyword2"});
image.setPosition(5);
image.update(); // calls (images.changeSettings; images.changePosition).

If you want, I could help you out with this. Let me know.

-- Anton Spaans.

[rkalla]

Anton,
That's a pretty damn cool idea.

You are right the current API is a 1:1 match against the existing Smug JSON API.

I'm finished 1.2.0 right now (documentation and convenience methods, along with a ton of optimizations, running changelog here: http://kallasoft.com/smugmug-java-api/changelog/) and starting on 1.2.1, so I don't have time to write an abstraction farther up the stack like you suggest but it would be a really nice thing to have.

Before you got started on an additional layer to the API, I'd almost suggest you implement some basic logic first using the API that is there and see what it ends up looking like.

If you see room for improvement of say 50% or more, I'd say another API to reduce the complexity would be greate... but if you notice that it wouldn't save *that* much effort, compared to the time and cost of implementing and maintaining/extending an additional API, maybe you and I could discuss additions at the core level to come to a middle ground of usability?

I am trying hard to keep a very close match to the Smug JSON API, but for the sake of convenience, I certainly wouldn't object to adding an additional *.support package that provided simplified access and use of the API if the use-cases definately justified it.

[flyingdutchie]

Thanks for your quick reply.

I'm going to try something out soon and see if it would save time. I would guess so ; hiding implementation details, abstracting it more into 'what' can be done instead of 'how' it is done, usually saves time for the user (programmer in this case).

I'll keep you updated.

BTW: i probably need an API key to test things out. Since i don't have an application yet, is it hard to get an API key from Smugmug?

[devbobo]

nice work Riyad, it was great chatting to you the other day

[rkalla]

Originally Posted by flyingdutchie

Thanks for your quick reply.

I'm going to try something out soon and see if it would save time. I would guess so ; hiding implementation details, abstracting it more into 'what' can be done instead of 'how' it is done, usually saves time for the user (programmer in this case).

I'll keep you updated.

BTW: i probably need an API key to test things out. Since i don't have an application yet, is it hard to get an API key from Smugmug?

Anton, it's super easy. If you login to your Smug account, go to Control Panel, and under Setting you should be able to request an API Key (or it will list the one you've requested)

Then it's automatically given to you and registered. It's just a way Smug can use to track software using their API system (e.g. 11k requests from a spam bot requesting images or something)

[rkalla]

Originally Posted by devbobo

nice work Riyad, it was great chatting to you the other day

Ditto, it was great to put a voice with a name... unfortunately for me you have a much cooler accent than I do

[flyingdutchie]

Originally Posted by rkalla

Anton, it's super easy. If you login to your Smug account, go to Control Panel, and under Setting you should be able to request an API Key (or it will list the one you've requested)

Then it's automatically given to you and registered. It's just a way Smug can use to track software using their API system (e.g. 11k requests from a spam bot requesting images or something)

Aha! I can use the key i got that is used for SmugMaps (mashup with google)...

Thanks!

[rkalla]

Originally Posted by flyingdutchie

Aha! I can use the key i got that is used for SmugMaps (mashup with google)...

Thanks!

No problem.

[flyingdutchie]

I have 2 questions for you.

1. The package name of your API.
   It includes the version, even the minor-version and build-number. This means that at every update, source-code that uses your API needs to be changed and re-compiled. I can understand the inclusion of a major-version number in the path, but minor version and build-number should not go in there.
2. The package com.kallasoft.smugmug.api.json.v1_2_0.albumtemplates.
   Your code (Get.GetResponse(String responseText)) iterates over the returned album-templates (albumTemplateArray) but instead of adding objects to an array, it repeatedly assigns the attributes of the same and only GetResponse object.
   

BTW: Its not hard wrapping my objects around your API (that sounds almost dirty.... ). It works great.

[rkalla]

Originally Posted by flyingdutchie

I have 2 questions for you.

1. The package name of your API.
   It includes the version, even the minor-version and build-number. This means that at every update, source-code that uses your API needs to be changed and re-compiled. I can understand the inclusion of a major-version number in the path, but minor version and build-number should not go in there.
2. The package com.kallasoft.smugmug.api.json.v1_2_0.albumtemplates.
   Your code (Get.GetResponse(String responseText)) iterates over the returned album-templates (albumTemplateArray) but instead of adding objects to an array, it repeatedly assigns the attributes of the same and only GetResponse object.
   

BTW: Its not hard wrapping my objects around your API (that sounds almost dirty.... ). It works great.

Great questions, let me try and address them:

1. The version in the package aren't *my* revisions, those are the API-versions that those classes are compatible with. Unfortunately because of how Smug versions and does releases "1.2.0" will be an API release that stays online for years to come for backward compatability, same with 1.2.1, and 1.2.2 and 1.3 and so on.

Also while there is a lot of overlap, there are also subtle changes between each release, different return types, extra arguments and so on. So I can't have just a "1.2" package that includes support for 1.2.1, 1.2.2, 1.2.3 and so on, because (for example) album.getInfo might be totally different from 1.2.1 to 1.2.3

That being said, if you build your API ontop of 1.2.0 package branch, it will always be there. Over time, the API may grow to include 1.2.1 (working on now) and 1.2.2 and more, but 1.2.0 will always be there so you won't need to recompile or rebuild.

2. DOH ! Thanks for the catch, I'm fixing it right now, it will go into Beta 2

[flyingdutchie]

Originally Posted by rkalla

Great questions, let me try and address them:

1. The version in the package aren't *my* revisions, those are the API-versions that those classes are compatible with. Unfortunately because of how Smug versions and does releases "1.2.0" will be an API release that stays online for years to come for backward compatability, same with 1.2.1, and 1.2.2 and 1.3 and so on.

Also while there is a lot of overlap, there are also subtle changes between each release, different return types, extra arguments and so on. So I can't have just a "1.2" package that includes support for 1.2.1, 1.2.2, 1.2.3 and so on, because (for example) album.getInfo might be totally different from 1.2.1 to 1.2.3

That being said, if you build your API ontop of 1.2.0 package branch, it will always be there. Over time, the API may grow to include 1.2.1 (working on now) and 1.2.2 and more, but 1.2.0 will always be there so you won't need to recompile or rebuild.

2. DOH ! Thanks for the catch, I'm fixing it right now, it will go into Beta 2

Wow, that's a quick reply! Thanks! :)

About 1.
I understand. I did not know 1.2.1 version of the Smugmug API (as defined by smugmug) was different enough from 1.2.0 to warrant seperate code-bases.

As long as you include both 1.2.1 and 1.2.0 (and other versions in the future) inside your JAR, it should be fine. This won't force users of your Java-API to recompile when they start using a newer version of your Java-API JAR.

The best would be to remove version numbers (minor/buildnum) from package names entirely and maintain binary compatibility (through overloading and overiding, for example). But if Smugmug returns results that are too different from each minor version to another, then this may indeed not be possible.

About 2.
Thanks! Eagerly awaiting your newest version.

[devbobo]

Personally, I can't see the majority of the API changing that much. For the most part, existing methods shouldn't change greatly except for maybe some additional parameters.

[flyingdutchie]

Originally Posted by devbobo

Personally, I can't see the majority of the API changing that much. For the most part, existing methods shouldn't change greatly except for maybe some additional parameters.

Thanks!
If that is the case, then the version of the Smugmug API should not be in the package-name... Overloading and overriding should do the trick (maintaining binary compatibility going forward).

[rkalla]

Originally Posted by flyingdutchie

Thanks!
If that is the case, then the version of the Smugmug API should not be in the package-name... Overloading and overriding should do the trick (maintaining binary compatibility going forward).

*** I think I know why there is confusion about this Anton, please read my reply starting with "NOTE #1" below ***

Anton, can you give me a more specific example of what you mean?

For example, let's say I have:
album.GetInfo class, and it's implemented to support the SmugMug 1.2.0 API, where it takes arguments A/B and C, and returns values X, Y and Z.

Now let's say in SmugMug API version 1.2.2, David/Don make some changes, add 3 arguments to it (D, E and F) and change one of the return values from X to X2, and add 3 more... so now I need a new class album.GetInfo, that supports these new arguments, and parses these new return values.

So in order to keep these two classes separate, and clearly deliniated in the source tree of the API, I need to name the class something useful, like:
album.GetInfo122, and it would be defined:

public class GetInfo122 extends GetInfo

So I have to make a clear delineation at some point with the API that is supported by which class, I chose to do it at the package level because it's much cleaner and clearer to implementors what they are using.

I have a feeling I *might* be misunderstanding your request though. Could you clarify how you would solve the example problem above so I could get a better idea of what you mean?



NOTE #1: I just had a thought where the confusion might be coming from... the way SmugMug releases API revisions is that each version released *eventually* becomes a stable release but keeps the same version number.

So for example, when 1.2.0 came out, 1.2.1 *is not* a perfect super-set to 1.2.0, it is an entirely new branch that may or may not have different implementations to different methods. David continues to work on 1.2.0, implementing bug fixes as people find them.

Now that 1.2.1 is out in beta form, David will be working on it for a few months stabalizing it, adding functionality and documenting it. Then when 1.2.1 is declared stable, David will begin work (behind the scenes) on 1.2.2

This is a bit different from standard versioning schemes where the following is true:
1.2.3 == 1 major version, 2 minor version, 3 patch version

and the "patch version" can never break API compatability.

You can actually think of *every* version of the Smug API as a major version release, like:
1.0, 2.0, 3.0 etc....

So when you see the "patch level" in my package names, it's because that API will be live and stable for the rest of it's life, it's a snapshot in time and the next "patch level" could possibly be completely different than the last, *that* is why I have to do that.

So to make things easier, you could imagine that my package names were actually:
com.kallasoft.smugmug.api.json.v1
com.kallasoft.smugmug.api.json.v2
com.kallasoft.smugmug.api.json.v3

and so on... because that is essentially what it boils down to.




NOTE #2: While I understand that Don/David don't have plans to completely break compatability between releases, I don't want to run that risk, and design the API around the idea that everything is compatible, and then if Smug releases an incompatible change, have to *then* break apart the API into compatibility levels. That would be a complete API break to anyone building on it. The way it is right now, it can be extended and enhanced in parallel to any work Smug does and maintain complete compatability into the forseeable future.

I hope that helps clarify why it's designed the way it is. Maybe in the future if Don/David let me spec/reimplment the entire API for them, there might be a different process

[flyingdutchie]

Aha,

I understand Riyad.

I just assumed that Smugmug would adher to a standard versioning scheme and that 1.2.0 and 1.2.1 are different patch/build versions only, with a binaray compatibility.

But if they are too different, e.g. they are actually two different versions all together that break the promise of any binary compatibily, then I agree with you. To differentiate between them, the difference in package names is a good choice.

[flyingdutchie]

Hi Riyad,

The album's Get.GetResponse is missing information for the optional SubCategory. Album info and Category info is returned, but not for SubCategory.

BTW: If the Get.execute's "Heavy" attribute is set to "true", what does happen? What is the difference from setting it to "false"?

Thanks!
-- Anton.

[rkalla]

Originally Posted by flyingdutchie

Hi Riyad,

The album's Get.GetResponse is missing information for the optional SubCategory. Album info and Category info is returned, but not for SubCategory.

BTW: If the Get.execute's "Heavy" attribute is set to "true", what does happen? What is the difference from setting it to "false"?

Thanks!
-- Anton.

Anton thanks for keeping me honest. Both were fixed in Beta 2.

Keep the reports coming! (btw if you want, I can cut you a work-in-progress snapshot so you atleast have the latest build to work against. the images/categories/subcat methods aren't done being fixed up yet, but everything else has been and 1.2.1 support begun.)