REST V2009-07-01 Programs

From Wiki.zanox.com

Web Services | RESTful API V20090701

The programs RESTFul API resource enables the retrieval of advertiser programs and the automatic management of advertiser program applications. Prerequisite for a program application is the existence of an advertising space.

Program applications can be created, deleted and their properties retrieved via this API.

GET: Retrieving a single program item

Parameters

Name	Necessity	Parameter type	Description
connectid	mandatory	header parameter or query parameter	connectID is required for authorization.
program	mandatory	path parameter	ID of program item.
callback	optional	query parameter	Supported if format is JSON. Name of the JS function the result is wrapped in.

Example Request

// REST XML
http://api.zanox.com/xml/2009-07-01/programs/program/53?connectid=580599047DF8F5311043

// REST JSON
http://api.zanox.com/json/2009-07-01/programs/program/53?connectid=580599047DF8F5311043

// REST XML using Header Authorization
GET /xml/2009-07-01/programs/program/53 HTTP/1.1
Host: api.zanox.com
Date: Mon, 09 Jun 2008 08:17:35 GMT
Authorization: ZXWS 580599047DF8F5311043

Example Response

 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://api.zanox.com/namespace/2009-07-01/">
         <programItem id="49">
            <name>mypaper.de</name>
            <adrank>1.7</adrank>
            <applicationRequired>false</applicationRequired>
            <description>mypaper.de - the good office-onlineshop</description>
            <descriptionLocal><![CDATA[<b>Bei mypaper können Sie Büroartikel online bestellen.<br>
Schnell, sicher und günstig 20.000 Artikel für´s Büro, für die Schule, Uni oder zu Hause.
Individuelle Konditionen sind auf Anfrage möglich.]]]]>>]]></descriptionLocal>
            <products>17654</products>
            <vertical id="78">Retail&amp;Shopping</vertical>
            <regions>
               <region>DE</region>
               <region>AT</region>
            </regions>
            <categories>
               <category id="15">Office &amp; School</category>
            </categories>
            <startDate>2000-05-22T00:00:00.000+02:00</startDate>
            <url>www.mypaper.de</url>
            <image>http://ui.zanox-affiliate.de/images/programs/49/49_mypaper.gif</image>
            <currency>EUR</currency>
            <conditions>
               <leads>
                  <minfixed>0.3</minfixed>
                  <maxfixed>1.0</maxfixed>
               </leads>
               <sales>
                  <minpercent>8.5</minpercent>
                  <maxpercent>10.0</maxpercent>
               </sales>
            </conditions>
         </programItem>
 </response>

GET: Programsearch

Parameters

Name	Necessity	Parameter type	Description
connectid	mandatory	header parameter or query parameter	connectID is required for authorization.
q	optional	query parameter	Search string.
startdate	optional	query parameter	all programs who were activated after the specified startdate
partnership	optional	query parameter	null all DIRECT only programs with mandatory direct applications INDIRECT only programs without the need of direct application
hasproducts	optional	query parameter	true delivers only programs with number of products > 0
ip	optional	query parameter	Filters progams by region of a given IP, i.e. "217.132.19.1"
region	optional	query parameter	ISO 3166-1-alpha-2 code, i.e. "DE", "FR"
category	optional	query parameter	category ID (see GET: Returns all zanox program categories), i.e. "76", "23"
items	optional	query parameter	number of items in the result set [1..n] (default = 10; maximum = 50)
page	optional	query parameter	page position [0..n] (default: 0)
callback	optional	query parameter	Supported if format is JSON. Name of the JS function the result is wrapped in.

Example Request

// REST XML
http://api.zanox.com/xml/2009-07-01/programs?q=fashion&page=1&items=10&connectid=580599047DF8F5311043

// REST JSON
http://api.zanox.com/json/2009-07-01/programs?q=searchforsometext&page=1&items=10&connectid=580599047DF8F5311043

// REST XML using Header Authorization
GET /xml/2009-07-01/programs?q=searchforsometext HTTP/1.1
Host: api.zanox.com
Date: Mon, 09 Jun 2008 08:17:35 GMT
Authorization: ZXWS 580599047DF8F5311043

Example Response

 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://api.zanox.com/namespace/2009-07-01/">
	<page>0</page>
	<items>3</items>
	<total>2376</total>
	<programItems>
		<programItem id="1432" xml:lang="en">...</programItem>
		<programItem id="1436" xml:lang="en">...</programItem>
		<programItem id="1441" xml:lang="en">...</programItem>
	</programItems>
 </response>

GET: Returns all programs for a specified user adspace

This requests returns all advertiser programs that are accepted for this advertising space.

This request requires message authentication!

Parameters

Name	Necessity	Parameter type	Description
connectid	mandatory	header or query parameter	connectid is required for authorization to eliminate any possibility of data abuse.
timestamp	mandatory	header or query parameter	timestamp is required for authorization to eliminate any possibility of data abuse.
nonce	mandatory	header or query parameter	nonce is required for authorization to eliminate any possibility of data abuse.
signature	mandatory	header or query parameter	signature is required for authorization to eliminate any possibility of data abuse.
adspace	mandatory	path parameter	ID of the adspace.
items	optional	query parameter	number of items in the result set [1..n] (default = 10; maximum = 50)
page	optional	query parameter	page position [0..n] (default: 0)
callback	optional	query parameter	Supported if format is JSON. Name of the JS function the result is wrapped in.

Example Request

// REST XML
http://api.zanox.com/xml/2009-07-01/programs/adspace/121232?connectid=580599047DF8F5311043&date=Mon,%2009%20Sep%202008%2008:17:35%20GMT&signature=FN+JGAMxDShoyh3sfayql6jWCRc=&nonce=12345678912345678911

// REST JSON
http://api.zanox.com/json/2009-07-01/programs/adspace/121232?connectid=580599047DF8F5311043&date=Mon,%2009%20Sep%202008%2008:17:35%20GMT&signature=FN+JGAMxDShoyh3sfayql6jWCRc=&nonce=12345678912345678911

// REST XML using Header Authorization
GET /xml/2009-07-01/programs/adspace/121232 HTTP/1.1
Host: api.zanox.com
Date: Mon, 09 Jun 2008 08:17:35 GMT
Authorization: ZXWS 580599047DF8F5311043:FN+JGAMxDShoyh3sfayql6jWCRc=
Nonce: 12345678912345678911

Example Response

 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://api.zanox.com/namespace/2009-07-01/">
	<page>0</page>
	<items>3</items>
	<total>2376</total>
	<programItems>
		<programItem id="1432" xml:lang="en">...</programItem>
		<programItem id="1436" xml:lang="en">...</programItem>
		<programItem id="1441" xml:lang="en">...</programItem>
	</programItems>
 </response>

GET: Returns all zanox program categories

Parameters

Name	Necessity	Parameter type	Description
connectid	mandatory	header parameter or query parameter	connectID is required for authorization.
callback	optional	query parameter	Supported if format is JSON. Name of the JS function the result is wrapped in.

Example Request

// REST XML
http://api.zanox.com/xml/2009-07-01/programs/categories?connectid=580599047DF8F5311043
 
// REST JSON
http://api.zanox.com/json/2009-07-01/programs/categories?connectid=580599047DF8F5311043

// REST XML using Header Authorization
GET /xml/2009-07-01/programs/categories HTTP/1.1
Host: api.zanox.com
Date: Mon, 09 Jun 2008 08:17:35 GMT
Authorization: ZXWS 580599047DF8F5311043

Example Response

 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://api.zanox.com/namespace/2009-07-01/">
         <categories>
            <category id="10">Cars &amp; Motorbikes</category>
            <category id="11">Internet services</category>
            <category id="15">Office &amp; School</category>
            <category id="17">Family, Sports &amp; Games</category>
            <category id="18">Computer &amp; Game Consoles</category>
            <category id="19">News &amp; Information</category>
            .........
         </categories>
</response>

POST: Creating a new program application

The POST request operation with an programs URI creates a new advertiser program application for the given advertising space.

Any interface implementing this method MUST INFORM THE USER that he is bound to the program's Terms & Conditions!

Parameters

Name	Necessity	Parameter type	Description
connectid	mandatory	header or query parameter	connectid is required for authorization to eliminate any possibility of data abuse.
timestamp	mandatory	header or query parameter	timestamp is required for authorization to eliminate any possibility of data abuse.
nonce	mandatory	header or query parameter	nonce is required for authorization to eliminate any possibility of data abuse.
signature	mandatory	header or query parameter	signature is required for authorization to eliminate any possibility of data abuse.
program	mandatory	path parameter	ID of program.
adspace	mandatory	path parameter	ID of the adspace.
callback	optional	query parameter	Supported if format is JSON. Name of the JS function the result is wrapped in.

Example Request

// REST XML
http://api.zanox.com/xml/2009-07-01/programs/program/49/adspace/224242?connectid=580599047DF8F5311043&date=Mon,%2009%20Sep%202008%2008:17:35%20GMT&signature=FN+JGAMxDShoyh3sfayql6jWCRc=&nonce=12345678912345678911
 
// REST JSON
http://api.zanox.com/json/2009-07-01/programs/program/49/adspace/224242?connectid=580599047DF8F5311043&date=Mon,%2009%20Sep%202008%2008:17:35%20GMT&signature=FN+JGAMxDShoyh3sfayql6jWCRc=&nonce=12345678912345678911

// REST XML using Header Authorization
POST /xml/2009-07-01/programs/program/49/adspace/224242 HTTP/1.1
Host: api.zanox.com
Date: Mon, 09 Jun 2008 08:17:35 GMT
Authorization: ZXWS 580599047DF8F5311043:FN+JGAMxDShoyh3sfayql6jWCRc=
Nonce: 12345678912345678911

Example Response

 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://api.zanox.com/namespace/2009-07-01/">
	<programApplicationItem id="34734547">
           <program id="49">mypaper.de<program>
           <adspace id="123123">Test Ad<adspace>
           <status>confirmed<status>
	</programApplicationItem>
</response>

DELETE: Deleting an existing program application

A DELETE request using a programs URI removes an advertiser program application.

Parameters

Name	Necessity	Parameter type	Description
connectid	mandatory	header or query parameter	connectid is required for authorization to eliminate any possibility of data abuse.
timestamp	mandatory	header or query parameter	timestamp is required for authorization to eliminate any possibility of data abuse.
nonce	mandatory	header or query parameter	nonce is required for authorization to eliminate any possibility of data abuse.
signature	mandatory	header or query parameter	signature is required for authorization to eliminate any possibility of data abuse.
program	mandatory	path parameter	ID of program.
adspace	mandatory	path parameter	ID of adspace.
callback	optional	query parameter	Supported if format is JSON. Name of the JS function the result is wrapped in.

Example Request

// REST XML
http://api.zanox.com/xml/2009-07-01/programs/program/49/adspace/224242?connectid=580599047DF8F5311043&date=Mon,%2009%20Sep%202008%2008:17:35%20GMT&signature=FN+JGAMxDShoyh3sfayql6jWCRc=&nonce=12345678912345678911

// REST JSON
http://api.zanox.com/json/2009-07-01/programs/program/49/adspace/224242?connectid=580599047DF8F5311043&date=Mon,%2009%20Sep%202008%2008:17:35%20GMT&signature=FN+JGAMxDShoyh3sfayql6jWCRc=&nonce=12345678912345678911

// REST XML using Header Authorization
DELETE /xml/2009-07-01/programs/program/1/adspace/2 HTTP/1.1
Host: api.zanox.com
Date: Mon, 09 Jun 2008 08:17:35 GMT
Authorization: ZXWS 580599047DF8F5311043:FN+JGAMxDShoyh3sfayql6jWCRc=
Nonce: 12345678912345678911

Example Response

 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://api.zanox.com/namespace/2009-07-01/">
	<count>0</count>
</response>

Explanation of the Response objects

REST V2009-07-01 Programs

From Wiki.zanox.com

Contents

GET: Retrieving a single program item

Parameters

Example Request

Example Response

GET: Programsearch

Parameters

Example Request

Example Response

GET: Returns all programs for a specified user adspace

Parameters

Example Request

Example Response

GET: Returns all zanox program categories

Parameters

Example Request

Example Response

POST: Creating a new program application

Parameters

Example Request

Example Response

DELETE: Deleting an existing program application

Parameters

Example Request

Example Response

Explanation of the Response objects

Views

Personal tools

Navigation

Search

Toolbox