new API release - March 31st, 2005

[onethumb]

BIG changes! Here are the highlights:

- method names have dramatically changed. The old methods will still work, and probably will forever, but no promises. I strongly suggest you start using the new naming scheme. See the docs.

- new interface! REST! Some would argue it's even simpler than XML-RPC, and they might be right. See the docs.

- APIKeys! To curb abuse and increase our ability to track API usage, all uses of the API now require an API key. Easy to apply for, quick to obtain, you'll need it to use any of the new functions, new REST interface, etc. See the docs.

- New methods to let you manipulate Categories & SubCategories: rename, delete, etc.

- Stats methods to get hits and bytes sent per album and per photo.

- Bug fixes to quite a few methods to return the proper values (ints, bools, etc) and results.

I'm sure I've introduced bugs, so holler if you find some.

Don

[devbobo]

Don,

smugmug.images.get & smugmug.albumtemplates.get are returning method not found


David

BIG changes! Here are the highlights:

- method names have dramatically changed. The old methods will still work, and probably will forever, but no promises. I strongly suggest you start using the new naming scheme. See the docs.

- new interface! REST! Some would argue it's even simpler than XML-RPC, and they might be right. See the docs.

- APIKeys! To curb abuse and increase our ability to track API usage, all uses of the API now require an API key. Easy to apply for, quick to obtain, you'll need it to use any of the new functions, new REST interface, etc. See the docs.

- New methods to let you manipulate Categories & SubCategories: rename, delete, etc.

- Stats methods to get hits and bytes sent per album and per photo.

- Bug fixes to quite a few methods to return the proper values (ints, bools, etc) and results.

I'm sure I've introduced bugs, so holler if you find some.

Don

[rutt]

Are you planning on maintaining xml-rpc as well as rest? I hope so. Python support of xml-rpc is first class, but not so for rest.

Don, I think it would be really great when you have a change like this that is going to break everything, to publish the documentation, changes, etc, in advance and give us some time to get ready. Please?

[Cameron]

Don, I think it would be really great when you have a change like this that is going to break everything, to publish the documentation, changes, etc, in advance and give us some time to get ready. Please?
I agree -- I first noticed my PHP script returning an error and dug through the code for a bit before I came here to read about the API changes. A simple "the API will be changing" heads-up would have been helpful, even without other details. Perhaps a 1 week "grace period" where API calls work without keys would have been helpful.

[Nikolai]

As long as the old functionality keeps working "as is", at least for the time being, I'm all up for the changes!

I agree, sort of advance notice would be nice, but hey, sometimes $%it just happens:-)

I'l looking forward to see the REST:-)

One question: is your intension to
1) support/uprdage *both* branches (rpx-aml & rest),
or
2) the rpc-xml gets to rest:-) and REST will be the "main" API?

Thanks again for keep an eye of this area!

[Cameron]

As long as the old functionality keeps working "as is", at least for the time being, I'm all up for the changes!

I agree, but the old functionality isn't working "as is" -- I don't have an API Key yet and my scripts using the old API calls are failing due to 'invalid API key'. :cry
Oh well - I'm sure once I get the API Key things will work very well. I think it's great that Don and the rest of the crew are so actively trying to make the API a useful and powerful tool.

[onethumb]

Are you planning on maintaining xml-rpc as well as rest? I hope so. Python support of xml-rpc is first class, but not so for rest.

Don, I think it would be really great when you have a change like this that is going to break everything, to publish the documentation, changes, etc, in advance and give us some time to get ready. Please?

I did rigorous backwards compatibility testing so I really shouldn't have "broken everything".

Note what's not working that used to work and I'll get it fixed.

Don

[onethumb]

I agree -- I first noticed my PHP script returning an error and dug through the code for a bit before I came here to read about the API changes. A simple "the API will be changing" heads-up would have been helpful, even without other details. Perhaps a 1 week "grace period" where API calls work without keys would have been helpful.

All existing functionality continues to work, without Keys.

Come on guys, I'm not that stupid. There's a huge grace period where all the old calls work, there's no key required for anything that was old, etc etc.

If something's not working, it's an honest mistake and a bug, not intentional. Tell me which call isn't working, rather than complaining with zero details. :)

Don

[onethumb]

Obviously, the docs aren't clear enough, though it seems like it to me. :)

For the record: Both REST and XML-RPC will be jointly updated in lockstep. XML-RPC isn't going anywhere.

Of course, also for the record, the APIs are currently sans official support or endorsement. Use at your own risk. ;)

Don

[rutt]

All existing functionality continues to work, without Keys.

Come on guys, I'm not that stupid. There's a huge grace period where all the old calls work, there's no key required for anything that was old, etc etc.

If something's not working, it's an honest mistake and a bug, not intentional. Tell me which call isn't working, rather than complaining with zero details. :)

Don

Sorry. Zero details is right. I didn't even test. I just read what you wrote and assumed that you were announcing that it wasn't going to work. Sorry if I read it wrong, but it wasn't 100% clear and I didn't sleep so great last night anyway.

I'll test and let you know.

[onethumb]

Don,

smugmug.images.get & smugmug.albumtemplates.get are returning method not found


David

Silly typos. I assume you were talking about the XML-RPC interface?

Try now. :)

Don

[onethumb]

BIG changes! Here are the highlights:


Oh, yeah, and the API endpoints changed again. Just to be clear, the old endpoints still work and should continue to work for a long long time, but I'd shift to using the new ones (which are permanent, now, I promise!) for all future work.

Don

[rutt]

Smugmug.py does seem to work. Next time I'll try to be more empirical. Sorry.

Thanks, Don, for all the work on this. It really is a pleasure to have this interface.

[Cameron]

All existing functionality continues to work, without Keys.

Come on guys, I'm not that stupid. There's a huge grace period where all the old calls work, there's no key required for anything that was old, etc etc.

If something's not working, it's an honest mistake and a bug, not intentional. Tell me which call isn't working, rather than complaining with zero details. :)
Don If I thought you were stupid would I be paying you money? :thumb Sorry for the lack of details. I have a PHP script and am using XMP_RPC (with old API for the moment). "loginWithPassword" fails due to 'invalid API key'. Using the API key I just received, it works perfectly. Any idea why the old call with the API key would fail? I'm not sure (being new to this) which other details would be helpful - please let me know what else you need.

[onethumb]

If I thought you were stupid would I be paying you money? :thumb Sorry for the lack of details. I have a PHP script and am using XMP_RPC (with old API for the moment). "loginWithPassword" fails due to 'invalid API key'. Using the API key I just received, it works perfectly. Any idea why the old call with the API key would fail? I'm not sure (being new to this) which other details would be helpful - please let me know what else you need.

The API key for XML-RPC should only kick in if you're sending a Version that's equal to or greater than "1.1.0".

What Version are you sending?

Don

[Cameron]

The API key for XML-RPC should only kick in if you're sending a Version that's equal to or greater than "1.1.0".

What Version are you sending?

Don
That was it - I was sending "1.1". Thanks for the quick replies and sorry for any confusion. I didn't think about version control in the API. :dunno That's what I get for posting messages on little sleep. Now I know.

Would there be any advantage, in PHP, to use the REST interface? The XML-RPC classes available for PHP seem to work well. Thanks.

[Nikolai]

I agree, but the old functionality isn't working "as is"
Works like a charm. no api key, no rest.
Prolly something on your side, my man!

Cheers!:1drink

[onethumb]

That was it - I was sending "1.1". Thanks for the quick replies and sorry for any confusion. I didn't think about version control in the API. :dunno That's what I get for posting messages on little sleep. Now I know.

Would there be any advantage, in PHP, to use the REST interface? The XML-RPC classes available for PHP seem to work well. Thanks.

Whew. Glad to hear. :)

The interfaces are essentially identical, so which one to use is left up to the author. Both interfaces are easy to use and lightweight (as opposed to SOAP), so you can't really go wrong with either one.

Don

[dds]

Hi, I just got my API key and I'm trying to give the REST API a shot but so far I've had no luck, just a lot of invalid API key errors :wxwax

As a quick check that it should be working, in my browser I've been trying to hit this URL:
https://api.smugmug.com/hack/rest/?method=smugmug.login.anonymously&Version=1.1.0&APIKey=RealAPIKeyHere
with or without SSL, the response is invalid API key. AFACT this should be just like the sample request in the docs. Does it work for anyone else? If so, what browser/OS are you using?

[onethumb]

Hi, I just got my API key and I'm trying to give the REST API a shot but so far I've had no luck, just a lot of invalid API key errors :wxwax

As a quick check that it should be working, in my browser I've been trying to hit this URL:
https://api.smugmug.com/hack/rest/?method=smugmug.login.anonymously&Version=1.1.0&APIKey=RealAPIKeyHere
with or without SSL, the response is invalid API key. AFACT this should be just like the sample request in the docs. Does it work for anyone else? If so, what browser/OS are you using?

Give it a shot now.

Don

[dds]

Give it a shot now.

Don
Works! Thanks very much!

[Domino]

Whew. Glad to hear. :)

The interfaces are essentially identical, so which one to use is left up to the author. Both interfaces are easy to use and lightweight (as opposed to SOAP), so you can't really go wrong with either one.

Don Hi Don,

First of all I am new to this forum and just discovered the Smugmug API yesterday, although I am a Smugmug member for some time already. I really think this API is a bright idea!

Now about SOAP, I think if it does really suck or not is not the right question at least for two reasons:



As soon as you use the right tools to implement SOAP Web Services at server and client level, you do not have do worry about SOAP since you wont have anything to do with it, SOAP is handled by the WS platform you use. Two completely different and very good WS platforms are the Java one from Sun and the MS .NET.
SOAP Web Services are really getting well supported now, and will open your API to a wide range of users and developpers on any kind of platform.
I was not either that enthousiast about Web Services since as a consultant I HAD to investigate different solutions and develop WS based applications for one of my customers.
If you ever want some more details feel free to direct mail me.

Dominique

[onethumb]

Hi Don,

First of all I am new to this forum and just discovered the Smugmug API yesterday, although I am a Smugmug member for some time already. I really think this API is a bright idea!

Now about SOAP, I think if it does really suck or not is not the right question at least for two reasons:



As soon as you use the right tools to implement SOAP Web Services at server and client level, you do not have do worry about SOAP since you wont have anything to do with it, SOAP is handled by the WS platform you use. Two completely different and very good WS platforms are the Java one from Sun and the MS .NET.
SOAP Web Services are really getting well supported now, and will open your API to a wide range of users and developpers on any kind of platform.
I was not either that enthousiast about Web Services since as a consultant I HAD to investigate different solutions and develop WS based applications for one of my customers.
If you ever want some more details feel free to direct mail me.

Dominique

I'd hate for this to become a religious issue, so I'll try to be brief and just state that I've done quite a bit of research and quite a bit of playing around and it just doesn't seem to make sense.

Look at our API. It's incredibly simple, yet also incredibly powerful. SOAP adds so much more weight and complexity to something that really should be simple and elegant. It would take me a much longer time to build a SOAP interface than it did to do both REST and XML-RPC combined.

As a semi-final note, I've chatted with Jeff Bezos and Jeff Barr at Amazon about their web services (Jeff Barr is the guy in charge of that stuff there). They tell me that 85% of the AWS usage is REST, hardly any SOAP, and that processing and returning a REST call is 6X faster than a SOAP call. I believe both numbers, both from personal experience and comparing notes with the web services guys at eBay, PayPal, and Google.

In an interesting parallel, I've been a part of web application teams using Java in the past, and I have huge complaints about Java that closely parallel SOAP. Java may be great for doing complex things more easily, but it sure makes doing simple things far too complex. It's slow, bloated, difficult to scale, and really just gets in the way for something "simple" like a web application, IMHO. So I'm not terribly surprised that Java and SOAP play nicely together - they seem to have the same design mentality.

Whew. Hopefully this post hasn't started The Crusades all over again. :)

Don

[Domino]

I'd hate for this to become a religious issue, so I'll try to be brief and just state that I've done quite a bit of research and quite a bit of playing around and it just doesn't seem to make sense.

Look at our API. It's incredibly simple, yet also incredibly powerful. SOAP adds so much more weight and complexity to something that really should be simple and elegant. It would take me a much longer time to build a SOAP interface than it did to do both REST and XML-RPC combined.

As a semi-final note, I've chatted with Jeff Bezos and Jeff Barr at Amazon about their web services (Jeff Barr is the guy in charge of that stuff there). They tell me that 85% of the AWS usage is REST, hardly any SOAP, and that processing and returning a REST call is 6X faster than a SOAP call. I believe both numbers, both from personal experience and comparing notes with the web services guys at eBay, PayPal, and Google.

In an interesting parallel, I've been a part of web application teams using Java in the past, and I have huge complaints about Java that closely parallel SOAP. Java may be great for doing complex things more easily, but it sure makes doing simple things far too complex. It's slow, bloated, difficult to scale, and really just gets in the way for something "simple" like a web application, IMHO. So I'm not terribly surprised that Java and SOAP play nicely together - they seem to have the same design mentality.

Whew. Hopefully this post hasn't started The Crusades all over again. :)

Don
Although it doesn't have anyhing to do with a religious issue, I am afraid I cannot agree with you.
Anyway, I will not argue, it doesn't make any difference form me if you have or not a SOAP WS API. Just my 2 cents.

Congrats again for Smugmug.

Dominique

[jef]

I can't upload successfully with the new API. I'm using the new version string, new URLs, and my API key. When I try to call "http://upload.smugmug.com/hack/xmlrpc/ smugmug.images.upload" I get a method not found fault. When I switch the method name back to the old deprecated "upload", the upload works but the result I get is just an empty string, as if the API version was pre-1.0. Since my code depends on getting back the ImageID as the result, it thinks the upload failed.

I'm sure I could hack around this by ignoring the results from the upload and figuring out the new ImageID using smugmug.images.get, but I'd really rather not. Please look into this ASAP.

[Nikolai]

I can't upload successfully with the new API. I'm using the new version string, new URLs, and my API key. When I try to call "http://upload.smugmug.com/hack/xmlrpc/ smugmug.images.upload" I get a method not found fault. When I switch the method name back to the old deprecated "upload", the upload works but the result I get is just an empty string, as if the API version was pre-1.0. Since my code depends on getting back the ImageID as the result, it thinks the upload failed.

I'm sure I could hack around this by ignoring the results from the upload and figuring out the new ImageID using smugmug.images.get, but I'd really rather not. Please look into this ASAP.
It looks like your got your pawns all mixed up.
New method name does not work with this url.
Check the doc.

HTH

[onethumb]

I can't upload successfully with the new API. I'm using the new version string, new URLs, and my API key. When I try to call "http://upload.smugmug.com/hack/xmlrpc/ smugmug.images.upload" I get a method not found fault. When I switch the method name back to the old deprecated "upload", the upload works but the result I get is just an empty string, as if the API version was pre-1.0. Since my code depends on getting back the ImageID as the result, it thinks the upload failed.

I'm sure I could hack around this by ignoring the results from the upload and figuring out the new ImageID using smugmug.images.get, but I'd really rather not. Please look into this ASAP.

For XML-RPC, you do *not* want to use the XML-based submission methods, like http://upload.smugmug.com/hack/xmlrpc/smugmug.images.upload.

See the docs on "Uploading via POST".

Don

[jef]

I know about uploading via POST. I wrote my code to upload via XML-RPC to keep things simpler. It used to work. Are you saying you are no longer supporting that option?

What about the missing method name?

What about the empty string return?

[Nikolai]

I know about uploading via POST. I wrote my code to upload via XML-RPC to keep things simpler. It used to work. Are you saying you are no longer supporting that option?

What about the missing method name?

What about the empty string return?
I am using Upload via Post, and I am using RPC-XML - all since last November.
New API requires new url.
Upload via Post simply posts to the special (old) url, no method name is needed.

As to the errors you're getting - since you're using mismatching methods/urls/versions you can get all sort of funny things back:-)

Just follow the documents in the hack section.
Or download S*E, check all the logging options on and use the results as the working example.

HTH

Good luck!

[jef]

I don't know what you mean about mismatching. As far as I can tell I am following the current docs.

[jef]

Ok, while I was waiting for you to fix the bugs in uploading via XML-RPC, I decided to try uploading via POST. Again I am using version 1.1.0, my API key, and the new URLs. Following the instructions on the "XML-RPC: Uploading via POST" page, I posted to the URL "http://upload.smugmug.com/photos/xmladd.mg". This URLs times out. Uploading via POST does not work for me.

I also re-checked my previous findings. XML-RPC to "http://upload.smugmug.com/hack/xmlrpc/ smugmug.images.upload" gives a method not found fault. If I use the new URL with the deprecated method name "upload", the upload succeeds but the response is an empty string.

I remain without any working upload path.

[Nikolai]

Ok, while I was waiting for you to fix the bugs in uploading via XML-RPC
There is nothing to fix, except your own code.

I understand the feeling of frustration when the darn thing does not work (and some things in API still do not..), but in this case it's not SM problem.
Upload was working fine for the last few months, several of us 3d party guys used it successfully in a variety of tools: python, .NET, apple, win32, etc.

Here, I made an exta run of S*E to give you a working url and sample reply:


Multipart post to:

https://upload.smugmug.com/photos/xmladd.mg
Response:

<?xml version='1.0' encoding="iso-8859-1" ?>
<methodResponse>
<params>
<param>
<value>
<int>album id here</int>
</value>
</param>
</params>
</methodResponse>



I used hhtps, but it works with http, too.

HTH

PS
Read *all* the docs, man:-)

[jef]

I have read all the docs. As far as I can tell my code corresponds to them. You mentioned you saw a mismatch - what were you referring to? Please be specific.

[Nikolai]

I don't know what you mean about mismatching. As far as I can tell I am following the current docs.
Here it is :
"http://upload.smugmug.com/hack/xmlrpc/ smugmug.images.upload"

You're using old url with a new method.
No wonder you get "method not found"..

And by the way, this is all for base64 encoded upload, which is like 30% slower than its multipart POST based twin. Nobody's using it for months, AFAIK..
So unless you're pursuing purely academic goals I'd suggest you use upload via post, for which I already gave you an example...

HTH

[jef]

That is the URL specified on this page: http://www.smugmug.com/hack/xmlrpc-overview

My old-API code, still working as of this morning, used "http://upload.smugmug.com/xmlrpc/" Should I ignore the above doc page and go back to that?

I know that base64 encoding uses 33% more bytes. Since my network connection is fast, this is not significant. Especially compared to the many seconds of processing time once the image gets to smugmug. In any event, as I said, uploading via XML-RPC using the old API and old URLs was still working as of this morning.

[Nikolai]

That is the URL specified on this page: http://www.smugmug.com/hack/xmlrpc-overview

My old-API code, still working as of this morning, used "http://upload.smugmug.com/xmlrpc/" Should I ignore the above doc page and go back to that?

I know that base64 encoding uses 33% more bytes. Since my network connection is fast, this is not significant. Especially compared to the many seconds of processing time once the image gets to smugmug. In any event, as I said, uploading via XML-RPC using the old API and old URLs was still working as of this morning.
As I mentioned before, to the best of my knowledge nobody's using "upload" (since for the most of us speed still does matter - try upload 10Gb in one shot, and watch those 30% turning into hours:-), so there is a chance that this particular method actually felt through the cracks, and you're the first one to notice...

It will be up to Don then..

Good luck!

[jef]

So you have no comment on the doc page that gives the URL I am using?

[Nikolai]

So you have no comment on the doc page that gives the URL I am using?
I stopped using base64 upload method in January, never touched it since.. I was much more concerned over other APIs that did not work at the time..

[jef]

So when you said I was using the wrong URL, you were just confused. Ok.

[devbobo]

jef,

just to clarify, which method are you using...

Upload via post or smugmug.images.upload ??


David

[jef]

Ok, let's recap again.

When I use XML-RPC to "http://upload.smugmug.com/hack/xmlrpc/ smugmug.images.upload", I get a method not found fault.

When I use XML-RPC to "http://upload.smugmug.com/hack/xmlrpc/ upload", the upload succeeds but returns an empty string as the result, instead of the ImageID.

When I try to use POST to "http://upload.smugmug.com/photos/xmladd.mg", I just get a timeout.

[devbobo]

Jef,

I think the above mentioned doc is a be misleading...

for xml-rpc uploads using smugmug.images.upload use url...
http://upload.smugmug.com/hack/xmlrpc/


for uploads via POST use url...
http://upload.smugmug.com/photos/xmladd.mg

Hope this helps,

David

[devbobo]

Ok, let's recap again.

When I use XML-RPC to "http://upload.smugmug.com/hack/xmlrpc/ smugmug.images.upload", I get a method not found fault.

When I use XML-RPC to "http://upload.smugmug.com/hack/xmlrpc/ upload", the upload succeeds but returns an empty string as the result, instead of the ImageID.

When I try to use POST to "http://upload.smugmug.com/photos/xmladd.mg", I just get a timeout.
Has the 'Upload via POST' method ever worked for you ?

I think you will find most people here you that method.

Can you include your POSTDATA for the 'Upload via POST' method so we can have a look at it ?

David

[jef]

for xml-rpc uploads using smugmug.images.upload use url...
http://upload.smugmug.com/hack/xmlrpc/

for uploads via POST use url...
http://upload.smugmug.com/photos/xmladd.mg


Aren't those the URLs I just said I'm using? Am I failing to see some subtle difference in spelling or punctuation?

[jef]

Has the 'Upload via POST' method ever worked for you ?


I had never tried it before this morning when the problems with the regular method cropped up. I'm sure I'm calling it wrong. However, if this upload method's idea of error reporting is to time out, I'm not real interesting in debugging my call.

[devbobo]

I had never tried it before this morning when the problems with the regular method cropped up. I'm sure I'm calling it wrong. However, if this upload method's idea of error reporting is to time out, I'm not real interesting in debugging my call.
lol...i understand your frustration.

My bet is that you're not creating the multi-part formdata correctly. With this method since you are posting data, like submitting a html form, if the data you post to the form is not correct, it is inconceivable that the page will never return anything.

It's pretty simple to work through and this is the "preferred" method for uploading, since you don't have to do the base64 encoding.

Just for reference here's sample postdata...

--111222111
Content-disposition: form-data;name="SessionID"

[SessionID]

--111222111
Content-disposition: form-data;name="Version"

1.0
--111222111
Content-disposition: form-data;name="AlbumID"

[AlbumID]

--111222111
Content-disposition: form-data;name="ByteCount"

[FileSize]
--111222111

Content-Transfer-Encoding: binary
Content-disposition: form-data;name="filename";filename="[FileName]"
Content-Type: image/jpeg
Content-Length: [FileSize]
[ImageData]
--111222111--

Hope this helps,

David

[jef]

As I said I am not interested in debugging Upload via POST.

What was the problem you saw with the URLs? I didn't see any difference between what I posted and what you posted.

[devbobo]

As I said I am not interested in debugging Upload via POST.

What was the problem you saw with the URLs? I didn't see any difference between what I posted and what you posted.
As it turns out there is no difference in the urls, I was composing that at the same time you were posting your reply.

Sorry

[devbobo]

When I use XML-RPC to "http://upload.smugmug.com/hack/xmlrpc/ smugmug.images.upload", I get a method not found fault.
jef,

sorry I was half asleep when I read this originally. If you are getting 'method not found', then that is a problem, I had this with a few functions calls for this new API release. It obviously hasn't been picked up since most people don't use that call.

Post this bug description as a new thread so that Don is more likely to see it.

David