RESTful API V20090701

From Wiki.zanox.com

Web Services | RESTful API V20090701

API Endpoints

Two different RESTful interfaces are available: XML and JSON. Both are available via http or https. The API can be used without a version parameter in the URL. If used without the version parameter the latest API version is always taken. In order to stick to a certain version the release date of the API has to be provided as a parameter.

http(s)://api.zanox.com/json/2009-07-01
http(s)://api.zanox.com/xml/2009-07-01

To see the differences between versions, please check Version History

zanox Connect API Authentification

API Version 2009-07-01 introduces the zanox Connect Authentification Model.

API Authentication

Two different types of authentication are necessary to use the RESTful API. More secure method calls generally require a hash-based signature. The implementation details can be found in the RESTful API authentication process section with zanoxConnect.

Callback Handler

The zanox API cannot be called via AJAX due to the same origin policy.

Instead, the API offers a callback parameter for use with a dynamic script tag.

Following are two examples of a product search for "auto" in the advertiser programs with ID 660, 10, 20, and 30.

Usage of 'callback=function' with static script tag

<script>
  function myCallbackHandler(jsonData){
  // Do something with the jsonData returned by the API query.
  }
</script>
<script src="http://api.zanox.com/json/2009-07-01/products?q=auto&programs=660,10,20,30&connectid=580599047DF8F5311043&callback=myCallbackHandler"> </script>

Usage of 'callback=function' with dynamic script tag

<script>
  function callAPI(url){
    var script = document.createElement('script');
    script.src = url; // Sets the script's source to the Rest/JSON API query.
    script.type = "text/javascript";
 
    document.getElementsByTagName('head')[0].appendChild(script); 
    // The browser performs a request to the zanox API. 
    // As soon as the script tag's source is loaded, the callback function is called.
    }
 
    function myCallbackHandler(jsonData){
    // Do something with the jsonData returned by the API query.
    }
 
  var url = 'http://api.zanox.com/json/2009-07-01/products?q=auto&programs=660,10,20,30&connectid=580599047DF8F5311043&callback=myCallbackHandler';
  callAPI(url); // This call could, for instance, be moved to an HTML element's "onclick" event
</script>

Both examples result in the dynamic creation and execution of the following:

 
<script>
myCallbackHandler({"page":0,"items":10,"total":85622,"query":"auto","productItems":{ ... });
</script>

API RESTful Resources

The RESTful API contains RESOURCES that can be accessed for various actions. Actions refers to the HTTP commands GET/POST/PUT and DELETE. The GET command means retrieving a resource, POST means creating a resource, PUT means updating a resouce and DELETE means removing a resource.

Resources are advertising spaces, product offerings, advertising media, advertiser programs, transaction reports and user profiles. Be aware that not all of these resources can be modified.

Products Resource

Using the REST V2009-07-01 Products you can access 70 mio product offer items using contextual product search, product download, incremental product download

Admedia Resource

With the REST V2009-07-01 Admedia you can access 300.000 advertising media (banners, text links, etc.)

Programs Resource

With the REST V2009-07-01 Programs you can search for affiliate programmes, retrieve affiliate programmes, and apply to affiliate programmes

Reports Resource

With the REST V2009-07-01 Reports you can retrieve Leads and Sales

Payments Resource

With the REST V2009-07-01 Payments you can do operations on payments

Adspaces Resource

With the REST V2009-07-01 Adspaces you can do operations on advertising spaces.

Profiles Resource

With the REST V2009-07-01 Profiles you can do operations on profiles