A linux mac os x command line interface

A linux mac os x command line interface

• 1.
  A  Linux/Mac  OS  X  Command  Line  Interface  to  AffiliateWindow   David  Walker,  Data  Management  &  Warehousing,  January  2010   Introduction     Affiliate  Window  offer  a  tracking  and  management  solutions  for  maintaining  an   affiliate  program.  This  works  by  directing  sales  to  a  merchant  from  an  affiliates’   website.   In   exchange   for   displaying   the   merchants’   advertising   the   affiliate   receives   commission   for   sales   that   originate   from   the   affiliate   site.   Affiliate   Window   (http://www.affiliatewindow.com)   are   one   of   the   market   leaders   in   providing  a  tracking  and  management  solution.     In  order  to  exchange  information  between  merchant  and  the  affiliate  there  is  an   API   for   exchange   of   data   via   XML   and   SOAP   over   HTTP(S).   AffiliateWindow   provide   a   comprehensive   description   of   the   API1   to   their   clients   and   a   PHP   example2,3  on  how  to  access  this  information.  This  example  is  very  powerful  for   those   organisations   that   have   PHP   development   resources   and   is   very   easy   to   integrate  with  PHP  based  websites  however  there  are  limited  resources  for  those   who   may   wish   to   use   other   development   tools,4   test   file   structures   from   the   command  line,  store  requests  and  responses  for  audit  purposes,  etc.     This   document   describes   a   way   to   use   the   interface   from   a   Linux   or   Mac   OS   X   command  line.   Pre-­‐Requisites     In   order   to   use   this   script   the   Linux   server   must   have   curl   installed   (available   on   Debian   based   systems   with   “apt-­‐get   install   curl”   and   on   RedHat   based   systems   with  “rpm  –Uvh  curl”  or  “yum  install  curl”.     Mac   OS   X   10.6   (Snow   Leopard)   and   potentially   earlier   versions   have   curl   pre-­‐ installed  so  no  further  installation  is  required.     In   addition   to   the   software   a   username   and   password   are   required.   These   are   available  from  AffiliateWindow.  It  is  also  useful  to  have  a  copy  of  the  API  to  hand.                                                                                                                     1   http://www.affiliatewindow.com/documents/affiliates/documentation/webser vices/affiliateservice/Affiliateservice_API_v3.pdf  (requires  login)   2  http://www.affiliatewindow.com/downloads/api.client.zip  (requires  login)   3  For  those  looking  for  further  information  of  the  PHP  packages  required  for   Linux  will  need  php  and  php-­‐soap.  If  these  are  installed  with  apt-­‐get,  yum  or  rpm   then  the  remaining  dependencies  will  automatically  be  installed   4  Whilst  researching  this  note  a  version  of  the  API  written  in  C#  was  found  at   http://awin.codeplex.com/    
• 2.
  The  Scripts     There   are   two   files.   The   first,   request.xml,   contains   the   request   in   XML   format   as   per  the  API.  The  second,  request.sh,  reads  request.xml  and  writes  response.xml   in   the   current   working   directory.   Debugging   can   be   assisted   by   changing   the   line   “curl  ”  to  be  “curl  –-­‐verbose  ”.     In   this   example   we   are   fetching   affiliate   transaction   data   using   the   example   from   the  API5.       <?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.affiliatewindow.com/"> <SOAP-ENV:Header> <ns1:UserAuthentication> SOAP-ENV:mustUnderstand="1" SOAP-ENV:actor=http://api.affiliatewindow.com/ <ns1:iId>YOUR_USERNAME_HERE</ns1:iId> <ns1:sPassword>YOUR_PASSWORD_HERE</ns1:sPassword> <ns1:sType>affiliate</ns1:sType> </ns1:UserAuthentication> <ns1:getQuota> SOAP-ENV:mustUnderstand="1" SOAP-ENV:actor=http://api.affiliatewindow.com/ True </ns1:getQuota> </SOAP-ENV:Header> <SOAP-ENV:Body> <ns1:getTransactionList> <ns1:dStartDate>2009-12-01T00:00:00</ns1:dStartDate> <ns1:dEndDate>2009-12-31T23:59:59</ns1:dEndDate> <ns1:sDateType>transaction</ns1:sDateType> </ns1:getTransactionList> </SOAP-ENV:Body> </SOAP-ENV:Envelope>     Figure  1  -­  request.xml       Since  we  are  fetching  affiliate  data  from  the  version  3  API  the  correct  URL  is  to   call   is   http://api.affiliatewindow.com/v3/AffiliateService.   To   fetch   merchant   data   the   URL   is   http://api.affiliatewindow.com/v3/MerchantService.   Note   that   the  path  (v3/AffiliateService  and  v3/MerchantService)  is  case  sensitive.                                                                                                                       5  The  namespace  setting  “xmlns:xsd=http://www.w3.org/2001/XMLSchema”   also  appears  in  the  example  but  it  is  not  used  by  PHP  example  code  and  was  not   seen  in  the  wireshark  trace  file.  
• 3.
  #!/bin/bash curl --user YOUR_USERNAME_HERE:YOUR_PASSWORD_HERE --data @request.xml -H "Content-Type: application/soap+xml" --output response.xml http://api.affiliatewindow.com/v3/AffiliateService     Figure  2  -­  request.sh  (curl  version)     The   curl   command   line   can   have   many   options.   In   this   example   the   important   things  to  note  are:     • The   @   before   the   data   file   that   instructs   curl   not   to   escape   the   payload   data.   • -­‐H   “ContentType:”   adds   a   header   that   is   essential   for   the   input   to   be   treated  as  a  SOAP  request  by  the  server.     It  is  also  possible  to  use  the  wget  command6  on  Linux  systems:       #!/bin/bash   wget --http-user=“YOUR_USERNAME_HERE” --http-passwd=“YOUR_PASSWORD_HERE” --header=“Content-Type: application/soap+xml” --post-file=“request.xml” --output-document=“response.xml” http://api.affiliatewindow.com/v3/AffiliateService Figure  3  -­  request.sh  (wget  version)   Debugging  can  be  added  by  changing  “wget  ”  to  “wget  -­‐-­‐debug  ”.     Note  that  these  scripts  have  only  been  tested  with  version  3  of  the  API  and  this   may  change  in  the  future  with  new  releases.   Background  Research     It   took   some   time   to   make   this   work.   In   the   end   WireShark7   was   run   to   packet   sniff   a   working   PHP   version   of   the   code.   The   important   aspect   of   making   this   work  appears  to  be  the  content  type  of  application/soap+xml  in  the  header.                                                                                                                   6  Available  on  Debian  based  systems  with  “apt-­‐get  install  wget”  and  on  RedHat   based  systems  with  “rpm  –Uvh  wget”  or  “yum  install  wget”   7  http://www.wireshark.org/