API Callbacks

[chrismajewski]

In the standard or not?

It's so well described by existing standard usage we can let API developers extend where required.

If we are to comment it should be to require callbacks, I have no strong opinion either way.

Open for comment.

[chrismajewski]

From previous discussion Ben Balter likes'em.

Little other comment in #2834

Barring further comment I will move forward with a strong recommendation leading to a requierment they be included. Little code, vital for some.

[chrismajewski]

Can't close this, can't be a requirement but could be an added suggestion.

[LaurentGoderre]

Are we talking about JSON callback?

[chrismajewski]

I'm flip flopping, comment, not comment. Maybe it's no more than a recommendation for a common callback name and behaviour. About as complex as below.

This came out of our first review of the WhiteHouse document: https://github.com/WhiteHouse/api-standards which referenced a stackoverflow page: http://stackoverflow.com/questions/2067472/what-is-jsonp-all-about?answertab=votes#tab-top

Everything below is from that stackoverflow solution:

For example, say the server expects a parameter called "callback" to enable its JSONP capabilities. Then your request would look like:

http://www.xyz.com/sample.aspx?callback=mycallback

Without JSONP, this might return some basic JavaScript object, like so:

{ foo: 'bar' }

However, with JSONP, when the server receives the "callback" parameter, it wraps up the result a little differently, returning something like this:

mycallback({ foo: 'bar' });

As you can see, it will now invoke the method you specified. So, in your page, you define the callback function:

mycallback = function(data){
  alert(data.foo);
};

And now, when the script is loaded, it'll be evaluated, and your function will be executed. Voila, cross-domain requests!

[LaurentGoderre]

I know all about that. If that is what we are talking about, JSONP should always be available when JSON is available.

[LaurentGoderre]

It is unfortunate though that is no standard for that parameter name but the standard should chose one so that all GC API use the same

[chrismajewski]

Yea, sorry... My default answer is always lowest barrier to entry.

If we do standardize on making JSON the only requirement out of the API then you can turn around and require that functionality. If we are doing both XML and JSON it just gets messy.

Left open for now, we'll discuss this more.

[LaurentGoderre]

Not having JSONP available can be a barrier for users of the API though.

[samperd]

I support having both json and xml. Callbacks should be encouraged, however may not be in a first iteration of an api.

[LaurentGoderre]

actually now that I have to rely a lot on JSON API, not having callback is one of the biggest sign of an API immaturity. Perhaps callback are only for another 5 years, until browser don't support CORS disappear but in the meantime, callback are a necessity if you want to allow anyone to use the API