Announcing: SmugMug Java API

rkalla · October 4, 2007

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 :barb

For the quick-clickers in the group, here are the links:
URL="http://kallasoft.com/smugmug-java-api/download/"]Download[/URL URL="http://www.kallasoft.com/projects/smugmug_java_api/documentation/api/"]Javadoc[/URL URL="http://www.kallasoft.com/projects/smugmug_java_api/documentation/manual/"]Manual[/URL URL="http://www.kallasoft.com/forum/viewtopic.php?f=4&t=3&p=3"]Announcement[/URL URL="http://kallasoft.com/smugmug-java-api/"]Homepage[/URL

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 :cry)

onethumb · October 4, 2007

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 · October 4, 2007

onethumb wrote:

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 · October 11, 2007

This is a nice library you wrote! <img src="https://us.v-cdn.net/6029383/emoji/thumb.gif" border="0" alt="" >

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 · October 11, 2007

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 · October 11, 2007

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 · October 11, 2007

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

rkalla · October 11, 2007

flyingdutchie wrote:

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 · October 11, 2007

devbobo wrote:

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 :cry

flyingdutchie · October 11, 2007

rkalla wrote:

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 · October 11, 2007

flyingdutchie wrote:

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

Thanks!

No problem.

flyingdutchie · October 18, 2007

Questions for you Riyad (found a bug?)
I have 2 questions for you.

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.
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.... :giggle). It works great.

rkalla · October 18, 2007

flyingdutchie wrote:

I have 2 questions for you.
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.

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.... :giggle). 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 · October 18, 2007

rkalla wrote:

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 · October 19, 2007

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 · October 19, 2007

devbobo wrote:

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 · October 19, 2007

flyingdutchie wrote:

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 · October 22, 2007

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 · October 24, 2007

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 · October 25, 2007

flyingdutchie wrote:

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.)

flyingdutchie · October 31, 2007

smugmug.albums.create: DefaultColor
Hi Riyad,

Trying to keep you honest again

.

In smugmug.albums.create, the parameter for DefaultColor is missing from your API.

rkalla · October 31, 2007

flyingdutchie wrote:

Hi Riyad,

Trying to keep you honest again .

In smugmug.albums.create, the parameter for DefaultColor is missing from your API.

Nice catch Anton, fixed!

(P.S.> I'm sending you a private build of Beta 2 tonight so you can build against that and be as current as possible)

flyingdutchie · November 13, 2007

I'm planning to add some search functionality as well.

I'll try to do this by embedding a small java-based database called SmallSQL (google it for more info).

I came up with this schema (representing Smugmug API 1.2.1) for the SmallSQL to allow some extended search capabilities:

Click on the image for a full-sized version.

The schema shows the available 'Smugmug Objects'. It show only some of the attributes for each of these objects. The ORDER and the STATS objects are disconnected:

STATS: I'm not sure they could be used in a meaningful way for searching.
ORDERS: Documentation of Smugmug API 1.2.1 is not mentioning any details for smugmug.orders.

When this schema and SmallSQL are embedded, searches can be done using SQL SELECT statements. SQL INSERT/DELETE/UPDATE statements and DDL statements should not be allowed by the user of the SmugFig API. Inserts, deletes and updates happen automatically.

rkalla · December 13, 2007

SmugMug Java API - Beta 2 Released
NOTE: Special thanks goes out to David Parry of the SmugMug team and Anton Spaans, author of SmugFig, for their assistence in the development of this release. Both put in a lot of time helping troubleshoot and refine the API for a much better end-user experience. Thanks guys!

Download | Documentation

The kallasoft SmugMug Java API is a Java API that provides integration with the SmugMug JSON API and is developed/released under the Apache License v2.0.

Beta 2 of the kallasoft SmugMug Java API has been released today and provides full support for the SmugMug JSON API v1.2.0 and partial support for SmugMug JSON API v1.2.1. This release represents the second release of the API and has gone a lot of refinement and improvement since Beta 1.

The simple examples page may give you a better idea of how to use the API out of the gate. 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.

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.

TODO List:

Add support for more 1.2.1 methods (focus on the payment and image operation methods first)
Change all primitive argument types to their Object counterparts.

Have fun and happy coding!

Full Changelog

Convenience methods added to every function so you no longer have to work with the cryptic execute(String, String[]) method calls.
Support for new Video URL arguments for uploaded videos (Video320URL, Video640URL, Video960URL and Video1280URL)
Support for SmugMunous added to the 1.2.0 and 1.2.1 APIs
All response properties changed from primitive types all to objects, which allowed the removal of unchecked exceptions reporting invalid values and simplified the API as well as usage of it.
users.getTree subcategory support added. Before only categories and their albums were returned, no consideration to subcategories was made.
Request/Response documentation updated with changed queries for 1.2.0
User-Agent header changed to report “kallasoft API/0.2.0″ where “0.2.0″ is replaced with whatever version of the API is being used.
Added beginning support for SmugMug API 1.2.1
Optimized response parsing to short-circuit if the response was an error
Optimized to fail-fast with partial, malformed or corrupted response (values pulled from JSON response are no longer checked for validity first, so errors with API can be detected right away and not hidden. Also removed the need for 1/2 the validity calls against the JSON API)
smugmug.users.getTree support for SubCategories returned in the response was added.
Logging was added to the API, using the SLF4J framework. The framework includes logging for all exceptions (as errors), a few strange cases that you should avoid (as warnings) a lot of processing and details (as debug messages) and some tracing messages if you are curious on watching the API’s execution flow.
- This can all be controlled with a LogBack configuration file. A default one that hides all non-error logging is provided by default so the API is “quiet”.
- NOTE: Even though the kallasoft SmugMug Java API already uses Jakarta Commons libraries that require Commons-Logging, Commons-Logging is not a good logging framework and the kallasoft SmugMug Java API may not have the same dependencies across it’s life span. So to decouple the framework from Commons-Logging, SLF4J support was integrated at the outset.
HttpClient used massively optimized according to the HttpClient Performance Guide.
- Instead of every method call creating an HttpClient instance before calling SmugMug then throwing it away, there is now only one singleton instance of HttpClient used by every request, every time.
- A MultiThreadedHttpConnectionManager is used with the singleton HttpClient to guarantee that multi-threaded use is safe.
- The response from HttpClient is now streamed directly out of the connection instead of being cached in memory, then copied out.
RuntimeJSONException added. It wraps the checked-exception JSONException from the JSON.org API. Previously all these parse exceptions were caught and stack traces printed out, but it could possibly be valuable for implementors to be able to catch those exceptions and respond to them. RuntimeJSONException will catch the JSONExceptions throw during parsing, and rethrow as an unchecked RuntimeException that can optionally be caught and processed.
NetworkException is a RuntimeException introduced to encapsulate all potential networking problems that can occur while using the API. Now implementors can simply catch the NetworkException and handle it as they see fit. Additionally getCause can be used to retrieve the more specific exception that occurred (e.g. UnknownHost, NoRouteToHost, ConnectionDenied, etc.)

flyingdutchie · December 17, 2007

rkalla wrote:

NOTE: Special thanks goes out to David Parry of the SmugMug team and Anton Spaans, author of SmugFig, for their assistence in the development of this release. Both put in a lot of time helping troubleshoot and refine the API for a much better end-user experience. Thanks guys!

Download | Documentation

The kallasoft SmugMug Java API is a Java API that provides integration with the SmugMug JSON API and is developed/released under the Apache License v2.0.

Beta 2 of the kallasoft SmugMug Java API has been released today and provides full support for the SmugMug JSON API v1.2.0 and partial support for SmugMug JSON API v1.2.1. This release represents the second release of the API and has gone a lot of refinement and improvement since Beta 1.

The simple examples page may give you a better idea of how to use the API out of the gate. 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.

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.

TODO List:
Add support for more 1.2.1 methods (focus on the payment and image operation methods first)

Change all primitive argument types to their Object counterparts.

Have fun and happy coding!

Full Changelog
Convenience methods added to every function so you no longer have to work with the cryptic execute(String, String[]) method calls.

Support for new Video URL arguments for uploaded videos (Video320URL, Video640URL, Video960URL and Video1280URL)

Support for SmugMunous added to the 1.2.0 and 1.2.1 APIs

All response properties changed from primitive types all to objects, which allowed the removal of unchecked exceptions reporting invalid values and simplified the API as well as usage of it.

users.getTree subcategory support added. Before only categories and their albums were returned, no consideration to subcategories was made.

Request/Response documentation updated with changed queries for 1.2.0

User-Agent header changed to report “kallasoft API/0.2.0″ where “0.2.0″ is replaced with whatever version of the API is being used.

Added beginning support for SmugMug API 1.2.1

Optimized response parsing to short-circuit if the response was an error

Optimized to fail-fast with partial, malformed or corrupted response (values pulled from JSON response are no longer checked for validity first, so errors with API can be detected right away and not hidden. Also removed the need for 1/2 the validity calls against the JSON API)

smugmug.users.getTree support for SubCategories returned in the response was added.

Logging was added to the API, using the SLF4J framework. The framework includes logging for all exceptions (as errors), a few strange cases that you should avoid (as warnings) a lot of processing and details (as debug messages) and some tracing messages if you are curious on watching the API’s execution flow.
This can all be controlled with a LogBack configuration file. A default one that hides all non-error logging is provided by default so the API is “quiet”.

NOTE: Even though the kallasoft SmugMug Java API already uses Jakarta Commons libraries that require Commons-Logging, Commons-Logging is not a good logging framework and the kallasoft SmugMug Java API may not have the same dependencies across it’s life span. So to decouple the framework from Commons-Logging, SLF4J support was integrated at the outset.

HttpClient used massively optimized according to the HttpClient Performance Guide.
Instead of every method call creating an HttpClient instance before calling SmugMug then throwing it away, there is now only one singleton instance of HttpClient used by every request, every time.

A MultiThreadedHttpConnectionManager is used with the singleton HttpClient to guarantee that multi-threaded use is safe.

The response from HttpClient is now streamed directly out of the connection instead of being cached in memory, then copied out.

RuntimeJSONException added. It wraps the checked-exception JSONException from the JSON.org API. Previously all these parse exceptions were caught and stack traces printed out, but it could possibly be valuable for implementors to be able to catch those exceptions and respond to them. RuntimeJSONException will catch the JSONExceptions throw during parsing, and rethrow as an unchecked RuntimeException that can optionally be caught and processed.

NetworkException is a RuntimeException introduced to encapsulate all potential networking problems that can occur while using the API. Now implementors can simply catch the NetworkException and handle it as they see fit. Additionally getCause can be used to retrieve the more specific exception that occurred (e.g. UnknownHost, NoRouteToHost, ConnectionDenied, etc.)

Great work, Riyad!

Somewhere around New Year, just before or just after 1/1/2008, i will release my initial version of SmugFig API. It will work together with Riyad's M2 (Beta 2) release.

I tried to get it done by this week, but that's not happening

. Going on vacation tomorrow.

rkalla · December 17, 2007

flyingdutchie wrote:

Great work, Riyad!

Somewhere around New Year, just before or just after 1/1/2008, i will release my initial version of SmugFig API. It will work together with Riyad's M2 (Beta 2) release.

I tried to get it done by this week, but that's not happening . Going on vacation tomorrow.

Thanks Anton. Have fun on the vacation. You have to forget about all code-related things when you go on vacation, it's a rule

rkalla · March 8, 2008

SmugMug Java API - Beta 3 Released
NOTE: Special thanks goes out to David Parry of the SmugMug team and Anton Spaans, author of SmugFig, for their assistence in the development of this release. Both put in a lot of time helping troubleshoot and refine the API for a much better end-user experience. Thanks guys!

Download | Documentation

The kallasoft SmugMug Java API is a Java API that provides integration with the SmugMug JSON API and is developed/released under the Apache License v2.0.

The simple examples page may give you a better idea of how to use the API out of the gate. 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.

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.

Beta 3 of the kallasoft SmugMug Java API has been released today and provides full support for the SmugMug JSON API v1.2.0 and partial support for SmugMug JSON API v1.2.1 as the 1.2.1 library is still under heavy development and change.

This release represents the third release of the API and has gone a lot of refinement and improvement since Beta 2.

(Announcement at Digital Grin)

Full Changelog

Support for Hidden added for images
Added support for Title argument for album.ChangeSettings method
Added support for Video (320/640/960/1280) transfer stats to users.GetTransferStats, albums.GetStats, images.GetStats methods
Support for users.GetTransferStats Heavy and non-Heavy results
albums.GetInfo and images.GetInfo were changed to return the Album and Image entity type respectively instead of having an internal duplicate of that class. This centralizes changes and future changes in the API to a single class, making it more robust and less likely to break your application built on the API as the SmugMug API changes.
Support for the new security changes in the SmugMug API was added (see this thread)
- Half of the changes were with respect to Responses now included the key information when appropriate. The other half were to new Key arguments (outlined below)
- The ordering of the arguments for the following methods changed (by adding a Key arg):
  - smugmug.albums.getInfo (AlbumKey)
  - smugmug.images.get (AlbumKey)
  - smugmug.images.getInfo (ImageKey)
  - smugmug.images.getURLs (ImageKey)
  - smugmug.images.getEXIF (ImageKey)
The “highlight” property of an Album now represents an Image (ID and Key) and not just the Image ID.
albums.getStats was changed to return an AlbumTransferStat entity instead of duplicate the class entirely.
images.getStats was changed to return an ImageTransferStat entity instead of duplicate the class entirely.
All constants defined for Albums and AlbumTemplates were moved from the 4 associated method classes to the single entity.Album class to help normalize the code.
Album & AlbumTemplate arguments normalized across the 2 entity classes and 4 method operations, in previous releases some of these arguments were missing.
Fixed a handful of stray bugs that had to do with argument or parameter mismatches or incorrect Boolean-to-String conversions for Smug.
1.2.1 albumtemplates.Create/ChangeSettings/Delete were added.
All 1.2.0 and 1.2.1 method arguments were changed from using primitives to using Objects. Now all arguments are optional and handled gracefully if omitted. You can simply pass null now for unknown values.
UploadHTTPPut’s execute implementation was broken up into a execute & executeImpl pair exactly as AbstractMethod provides executeImpl. This allows subclasses to more closely control custom uploading implementations and how to handle the returns JSON response, before the single execute method was written to return a UploadHTTPPutResponse making it very difficult for subclasses to further customize the return at all without hacking up wrapper/delegate Response implementations. This brings the binary upload implementation inline design-wise with the remainder of the API and as flexible as possible while still maintaining the simple ease of use and extensibility.
Dependency on Commons Logging removed
Dependency on Commons Lang removed

devbobo · March 8, 2008

Nice work Riyad

rkalla · March 8, 2008

devbobo wrote:

Nice work Riyad

Thanks in a large part to you David and all the help you sent my way keeping me honest with the changes.

flyingdutchie · March 16, 2008

Hi everyone,

I just released a new version of the SmugFig API. It's version 0.1.1 and can be found here.
http://blog.antonspaans.com/smugfig-api/

Riyad and David, thank you very much for the help and support you have given me throughout the implementation of this API.

Here is 0.1.1's change-log

Fixed a bug in SubCategoryPrototype>>getAll(int ID).

mData.getCategoryID() was used instead of the provided ID.

Fixed a bug in the cache handling of the postGetAll method.

All objects in the named cache are returned, not the particular (modified) subset that is equal to the input of this postGetAll method. (still to do).

Added user.getTree method. This Smugmug method will be handled by the Account.getSmugObjectsHierarchy.

Added functionality to be able to refresh subsets of caches.

Added getAllFromCache() method to ISmugObjectProtoype interface and the implementing classes.

Added getAllFromCache(String subSetId) method to ISmugObjectProtoype interface and the implementing classes.

Added getParentId() to ISmugObject interface and implementing classes. This id is used for the subSetId.

Added support for smugmug-api-0.3.0

Added support for the new Smugmug security changes.

Album titles can now be updated.

Images now have a 'IsHidden' attribute.

Added 'getFileName()' to the Image class.

Added asynchronous smugmug-operations to ISmugObject and ISmugObjectPrototype.

Added GUIDs: Smugmug Objects can handle them now (initial implementation).

Improved the java-generics of the API

An Image's TinyURL was not properly retrieved from the Smugmug Repository.

Added two methods to the Session class to allow downloading of the owner's private images.

dound · March 19, 2008

flyingdutchie wrote:

I'm planning to add some search functionality as well.

I'll try to do this by embedding a small java-based database called SmallSQL (google it for more info).

I like the sound of this. Looking at your source, it seems like you might be toying with using Derby instead (that's what I see in com.streetsofboston.smugmug.v1_2_1.db.DataBase)? I haven't looked through all this very carefully yet, but I guess this portion of the code wasn't really intended to be part of the release which is used since the database file is hard-coded to a location on your drive (D:\...).

What's the state of this functionality?

Sounds exciting

.

Announcing: SmugMug Java API

Comments