Common API Query Parameters

Web Services - Common API Headers and Parameters

HTTP Headers

X-Requested-With

For APIs which require this header, this header can be set to any value. Javascript toolkits typically set this to XMLHttpRequest when making requests from the browser.

This header is required to defeat cross-site request forgery. Because the service api is written in a way that allows it to be used from HTML forms, we must defend against form submissions generated by third-party sites. You can't set a custom HTTP header using an HTML form, so most POSTs require this custom header. The form_upload service is an exception - in order to support HTML input type="file" forms, it doesn't require X-Requested-With.

Parameters

callback string containing a javascript object/array reference

The callback parameter causes a JSON response from the server to wrapped as a JSONP response. The response Content-type is forced to "text/javascript", the HTTP status is forced to "200 OK", and in the case of /trans services the response document is wrapped with an additional JSON envelope. Any binary content is base64 encoded before being embedded in the JSONP response.

onsucceed uri_template

The onsucceed parameter causes a successful response to return a 301 redirect instead of a 200 OK. The target url is built by substituting variables from the response into the URI template value of the argument. The variables available vary from service to service.

This supports a style of client that uses HTML forms to drive the service api. These clients haven't turned out to be common and understanding how to build them is somewhat convoluted, so we might be able to deprecate this parameter. The only place where it is hard to do without is in the form_upload service.

onfail uri_template

This is similar to the onsucceed parameter, but it is used to handle error responses and provides a different set of variables for substitution

Edit description

Search Help Center

Discussions

There are no conversations on this topic. Would you like to start one?

Start the Discussion »