Getting Started Tutorial

From Wiki.zanox.com

Jump to: navigation, search

Contents

[edit] Getting Started with zanox Webservices

Here is a getting-started-quickly example for the zanox webservices. This example is both for the Rest-API as well as for the SOAP-API. Goal of this tutorial is to set up a small and quick product search and to introduce newbies to the zanox web services. After you have understood this tutorial, you will be able to use all the zanox web services by applying your knowledge learned here.

Hint
The examples here are pseudo-code and can be easily adopted to any programming language of your choice.

First: register for the zanox webservices

Then: decide which programming language and which API you want to use:

We first explain the REST-solution, then the SOAP-solution

[edit] REST-solution

[edit] 1. Basic HTML

To perform the zanox product search first set up an HTML-Page containing a form (from where to search from), and an area where the result is displayed (eg. a textarea): 

<html>
 <head>
     <title>Product search: zanox webservices example</title>
 </head>
 <body>
       <form action="#" method="get">    
           <input type="text" name="search" value="Searchstring" />
           <input type="submit" value="Produkte suchen" />
       </form>
       <textarea style="width: 100%;height: 10%;">$Result</textarea>
 </body>
</html>

[edit] 2. Set Variables

Then: setup all the stuff (variables, strings etc) needed: 

var: 'zanox_server' = 'http://api.zanox.com'
var: 'zanox_host' = 'api.zanox.com'
var: 'zanox_Request_Method' = 'GET'

var: 'zanox_applicaton_id' = (UTF-8:'ZXWS 1234567890987654321')
var: 'zanox_shared_key' = 'abcdefghijklmnopqrstuvwxyz'
Screenshot
Screenshot

You will find these keys in your zanox account : login, go to tab "Webservices". You'll find the application id under "Application ID" and the shared key under "Shared Key". See the Create Authentication Credentials page for more details on this. 

var: 'zanox_get_param_date' =gmtdate()

The date must fit and be formatted GMT: "Mon, 09 Jun 2008 08:17:35 GMT" 

 var: 'zanox_Resource_URL' = '/products?q='+$search

This is the service-resource you are using. Here: simple product search, later you can adjust this string if you want to use other resources 

var: 'zanox_string2sign' = (UTF-8: ($zanox_Request_Method + $zanox_Resource_URL + $zanox_get_param_date))
var: 'zanox_signature' = (Encrypt_HMAC_SHA1_BASE64: $zanox_string2sign,$zanox_shared_key)
var: 'zanox_applicaton_id_security' = $zanox_applicaton_id + ':' + $zanox_signature

var: 'zanox_Request_URL' =      $zanox_server+'/xml'+$zanox_Resource_URL

Use /xml if you want XML output, otherwise use /json for JSON output. (Do not forget the leading slash).

Note
You have to check the documentation of your chosen programming language, to identify which functions are provided to do:
  1. UTF-8-encoding (the red-printed function "UTF-8" in this example)</li>
  2. HMAC+SHA1 encryption (the red-printed function "Encrypt_HMAC_SHA1_BASE64" in this example)</li>

[edit] 3. Send Request

Now its almost finished. Just send your request, and you will receive your result: 

var: 'Result' = (HTTP_GET: $zanox_Request_URL,Headers=(
                                                     'Date' = $zanox_get_param_date,
                                                     'Authorization' =  $zanox_applicaton_id_security
                                                     )
               )

That's it! The variable "Result" now contains the response to your query (either json or xml). Now you just have to parse out all the content you need, and your finished! Hooray!

[edit] SOAP-solution

[edit] 1. Basic HTML

To perform the zanox product search first set up an HTML-Page containing a form (from where to search from), and an area where the result is displayed (eg. a textarea): 

<html>
 <head>
     <title>Product search: zanox webservices example</title>
 </head>
 <body>
       <form action="#" method="get">    
           <input type="text" name="search" value="Searchstring" />
           <input type="submit" value="Produkte suchen" />
       </form>
       <textarea style="width: 100%;height: 10%;">$Result</textarea>
 </body>
</html>

[edit] 2. Set Variables

Then: setup all the stuff (variables, strings etc) needed: 

var: 'zanox_server' = 'http://api.zanox.com/soap/2008-05-21/'
var: 'zanox_host' = 'api.zanox.com'
var: 'zanox_Request_Method' = 'publisherservice'

var: 'zanox_applicaton_id' = '1234567890987654321'
var: 'zanox_shared_key' = 'abcdefghijklmnopqrstuvwxyz'
Screenshot
Screenshot

You will find these keys in your zanox account : login, go to tab "Webservices". You'll find the application id under "Application ID" and the shared key under "Shared Key". See the Create Authentication Credentials page for more details on this. 

var: 'zanox_get_param_date' =format(date())

The date must fit and be formatted like this: "2008-08-25T10:36:08.000Z" 

 var: 'zanox_Resource_URL' = 'searchproducts'

This is the service-resource you are using. Here: simple product search, later you can adjust this string if you want to use other resources 

var: 'zanox_string2sign' = (UTF-8: ($zanox_Request_Method + $zanox_Resource_URL + $zanox_get_param_date))
var: 'zanox_signature' = (Encrypt_HMAC_SHA1_BASE64: $zanox_string2sign,$zanox_shared_key)
Note
You have to check the documentation of your chosen programming language, to identify which functions are provided to do:
  1. UTF-8-encoding (the red-printed function "UTF-8" in this example)</li>
  2. HMAC+SHA1 encryption (the red-printed function "Encrypt_HMAC_SHA1_BASE64" in this example)</li>

[edit] 3. Build SOAP-Envelope 

 
 Var: 'Soap_Env' = '
 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://api.zanox.com/namespace/2008-05-21/">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:SearchProducts>
         <ns:query>'+$search+'</ns:query>
         <ns:region>DE</ns:region>
         <ns:minPrice>1</ns:minPrice>
         <ns:maxPrice>1000</ns:maxPrice>
         <ns:adspaceId>784330</ns:adspaceId>
         <ns:page>1</ns:page>
         <ns:items>10</ns:items>
		 <ns:applicationId>'+$zanox_applicaton_id+'</ns:applicationId>
      </ns:SearchProducts>
   </soapenv:Body>
 </soapenv:Envelope>
 '
 

[edit] 4. Send Request 

 Var: 'Result' = (Send_Soap: $zanox_server,
 -PostParams=$Soap_Env, 
 -SendMIMEHeaders,
 -Content-Type = 'text/xml; charset=utf-8',
 -Content-Length = $Soap_Env.bytes.length,
   )
  )

That's it! The variable "Result" now contains the response to your query in xml. Now you just have to parse out all the content you need, and your finished! Hooray!

[edit] Download this example

More in-depth details on how and why to authentify for REST API can be found in this wiki.

Retrieved from "http://wiki.zanox.com/en/Getting_Started_Tutorial"
Personal tools