IMPLEMENTATION GUIDE API Service More Power to You May 2008 For more information, please contact support@zedo.com
Implementation Guide ZEDO API Service Disclaimer This Implementation Guide is for informational purposes only. ZEDO MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT. The information contained in this document represents the current view of ZEDO Inc. as of the date of publication. ZEDO cannot guarantee the accuracy of any information presented after the date of publication. Complying with all applicable copyright laws is the responsibility of the user. No part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of ZEDO Inc. ZEDO may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from ZEDO, the furnishing of this document does not give the user any license to these patents, trademarks, copyrights, or other intellectual property. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, place or event is intended or should be inferred. The names of actual companies and products mentioned herein may be the trademarks of their respective owners. 2008 ZEDO Inc. All rights reserved. Copyright 2008 ZEDO Inc. Page 2 of 9
Implementation Guide ZEDO API Service Contents Introduction...4 Custom Solutions for Unique Business Needs...4 Application Scenarios...4 Use Case 1: Advanced Reporting for Marketers...4 Use Case 2: Automate Repetitive Data Entry Tasks...5 Use Case 3: Integration with 3rd Party Applications...5 How it Works...6 Step 1: Obtain the Z:API...6 Step 2: Generate the Web Service WSDL...6 Step 3: Import WSDL file to your development platform...6 Step 4: Build the custom application...7 Functional Specifications...8 Summary...8 Company Overview...9 Additional Reading...9 Copyright 2008 ZEDO Inc. Page 3 of 9
Introduction The ZEDO Application Programming Interface Service (Z:API) is a software toolkit to automate data communication between the ZEDO Ad Serving System and other third party applications. Z:API enables ZEDO customers and development partners to build add-on applications and data feeds to serve standard and custom-tailored business requirements. This Implementation Guide for Z:API is intended for use by developers needing to retrieve, update or create data in the ZEDO Ad Serving System. It is recommended that developers understand the following technologies: HyperText Transfer Protocol (HTTP) HyperText Markup Language (HTML) extensible Markup Language (XML) Simple Object Access Protocol (SOAP) Web Services Definition Language (WSDL) Custom Solutions for Unique Business Needs In today s business environment, constant innovation and adaptation has become the norm. ZEDO understands the need to meet evolving business demands, and has therefore developed Z:API, a API-based service that extends the flexibility and functionality of ZEDO s Ad Serving System. Z:API is developed using Java technology and built on Apache Axis2. It uses WSDL, which defines a standard way of describing a web service interface using XML. Z:API identifies with SOAP 1.1, which acts as a protocol that defines the structure of the XML documents used to send requests and receive responses from a web service. Z:API provides host of functions that allow you to manipulate data in the ZEDO System. Z:API can be integrated with third party applications where it facilitates data transfer across different systems. It can also be used to build customized ad serving applications. ZEDO Ad Hoc reporting is a perfect example of this. It s a reporting tool build using Z:API to retrieve data for Advertisers, Publishers, Channels, Campaigns and Creatives. Application Scenarios The following use cases illustrate common application scenarios to explain the benefits of using Z:API. These use cases are not intended as comprehensive and are for example purposes only. Use Case 1: Advanced Reporting for Marketers Goal: Develop a custom business reporting system. E.g: NetPromote is an Ad Marketer who wants to track more than just clicks. Scenario: NetPromote is focused on customer acquisition and aims to track campaignspecific ROI. It wants special reports to better strategize its business initiatives. ZEDO suggests NetPromote to build a custom reporting tool using Z:API, since Z:API allows creation of report templates that can be used to retrieve required data from the ZEDO System database.
NetPromote s development team uses Z:API Get functions to transfer the required data between the ZEDO Ad Serving System data store and their custom application. With these tailor-made reports, NetPromote is able to track actual individual conversions specific to each campaign. Use Case 2: Automate Repetitive Data Entry Tasks Goal: Automate the process of importing large datasets into the ZEDO Ad Serving System from a flat file (e.g. Excel to.cvs). E.g: Globalturf wants to import details of Advertisers, Publishers and Campaigns from an Excel file Scenario: Globalturf maintains an Excel file containing details of Advertisers and Publishers. Globalturf would like to automate the data entry from this spreadsheet in to the ZEDO System. Instead of manually creating new advertisers and publishers and filling all required onscreen forms. Globalturf s developers create a new application to read data from an Excel file and create an XML file. Then using Z:API Create and Update functions, create Advertisers and Publishers in ZEDO Ad Serving system. With Z:API, Globalturf is able to save significant amount of time usually spent in manually entering the details of new Advertisers and Publishers one at a time into the system. Use Case 3: Integration with 3 rd Party Applications Goal: Develop a backend interface with workflow system. E.g: FlairNetworks wants to build a backend interface between ZEDO Ad Serving and Solbright s Adsuite Scenario: FlairNetworks serves display ads across their network using ZEDO Ad Serving, but their direct sales team uses Solbright Adsuite to reserve campaigns and automate billing processes. FlairNetworks wants to build a backend interface to seamlessly interlink the two systems. FlairNetworks s developers create a web application using Z:API Get, Create, and Update functions to communicate with the Adsuite system. With the customized interface running in the background, FlairNetworks is able to optimize its existing process and improve its effectiveness.
How it Works The API development process is illustrated in Figure 1 below. Obtain ZEDO API Service Get the Web Service WSDL One time process Import WSDL file into development platform Build custom applications Write program code Regular process Compile and Run Figure 1: Z:API Development Process Step 1: Obtain the Z:API For more information about this premium feature, email sales@zedo.com or contact your ZEDO Account Manager directly. Once the service has been enabled for your network, you will be emailed a link to the necessary installation instructions to get started. Step 2: Generate the Web Service WSDL To access the ZEDO s web service you need a Web Service Definition Language (WSDL) file. The WSDL is an XML-based language that provides a model for describing Web services. The development platform uses this WSDL to generate Z:API client libraries to access the ZEDO Web service it defines. For more information about WSDL, see http://www.w3.org/tr/wsdl. You will be emailed access to the appropriate WSDL file once Z:API has been enabled for your network. Step 3: Import WSDL file to your development platform You will need to import the WSDL file into your development platform to generate the necessary objects used for building client web service applications. This section provides sample instructions for Apache Axis 2. Instructions for Java Environments (Apache Axis 2) Java Environments uses objects to access the API. These objects act as proxies to their server-side counterparts. The Java objects have to be generated from the WSDL file in order to use the API. Each SOAP client has its own tool for this process. You can use free Apache group WSDL2Java utility from Axis 2 project.
Preliminary Steps: Install Axis on your System. Set a reference to all of its component JAR files in your classpath using the syntax below: java classpath pathtojar/filename org.apache.axis.wsdl.wsdl2java -a pathtowsdl/wsdlfilename This command will generate a set of folders and Java source code files in the same directory in which it was run. After these files are compiled, they can be included in your Java programs for use in creating the client applications. For most Java development environments, you can use special tools to build stubs, skeletons, wrappers etc and to make call functions. For more information about using WSDL2Java, see http://ws.apache.org/axis/java/reference.html. Step 4: Build the custom application Once the WSDL file is imported, you can start building the client applications which will use Z:API functions. You can develop the application in a language of your choice (such as Java, Perl, Python, C, C++ and PHP). The client program should be able to send request to Z:API and tap the response received from it. Z:API processes the request and sets appropriate response. Since Z:API is a web service, you don t need any sort of installation for the API. You only need to install software for the language in which the application will be developed. The following program aims to retrieve Campaign details for a particular Campaign based on the Reference Id (asset_id) passed. Process Steps: 1. Note that Z:API has no standalone login or logout functions. Each function call must be provided with authentication data in SOAP header. For stubs that were generated using wsdl2java utility you need to follow the steps below: Create stub object to communicate with Z:API ServiceZEDOAPIStub.GetCampaign req = new ZEDOAPIStub.GetCampaign(); Insert user, password, network into SOAP message header stub._getserviceclient().addstringheader(new QName("http://api.zedo.com","user", "zedoapi"), "user@email.com"); stub._getserviceclient().addstringheader(new QName("http://api.zedo.com","password", "zedoapi"), "mypassword"); stub._getserviceclient().addstringheader(new QName("http://api.zedo.com","network", "zedoapi"), "525"); 2. Write the code: ZEDOAPIStub.GetCampaign req = new ZEDOAPIStub.GetCampaign(); req.setparam0(205054); ZEDOAPIStub.GetCampaignResponse res = stub.getcampaign(req); ZEDOAPIStub.Campaign ret = res.get_return();
3. Compile your code and run. Functional Specifications assertequals(205054, ret.getassetid()); The following specifications set out the range of functionality that ZEDO clients can expect from Z:API. Summary: All APIs provide secure access to ZEDO Ad Serving datastore. Get APIs fetch all or specific records. To retrieve specific set of records, relevant Reference Id(s) need to be passed as parameters. Update objects using their reference Id. Note that at a time, only object can be updated. Update APIs update all required fields for the record. To update specific set of records, relevant Reference ID(s) need to be passed as parameters. Create APIs insert new records into the appropriate ZEDO Ad Serving databases. All required fields must be entered, optional fields that are specified will insert with an empty string or values will be set automatically. Z:API attempts to mimic the structure of the data from the user interface of the ZEDO Ad Serving system. Input Validation A Z:API XML request should be a well formed SOAP request according to WSDL description. The BETA version of Z:API does not require a client-side first-level DTD or XMLSchema validation nor does it require second-level data validation. For an incorrectly formatted request, a standard SOAP error response will be generated by Z:API. For an invalid data request on a data field (e.g. an invalid Role ID in CreateUser), the request will fail and Z:API will return standard web service exception/error condition. For an invalid data request on non-bounded Bounded Data Certain fields in the user interface are inherently bounded. For example, you cannot create a Campaign for an Advertiser that has not been created in the ZEDO system. The same bounds are true when using Z:API. In constructing a Z:API request, you must use valid IDs for bounded data fields. Required Data Certain fields in the user interface are required/mandatory. For example, you cannot create a Campaign without providing a Campaign Name. In constructing any Z:API request, you must provide valid inputs for all required data fields. Summary ZEDO API Service is a high-level API that provides a portable and simplified interface for the application programmers to construct customized applications enhancing the functionalities of ZEDO Ad Serving. The API development feature is available to ZEDO Customers from version 7.1.0 onwards. Since the ZEDO API is an open API based on common web service standards, including SOAP and WSDL, it can be accessed from virtually any modern programming environment or integration tool. We welcome all bug reports or suggestions on how to improve the functionality of the API. ZEDO will do its best to incorporate your requests in the future releases of the API Development Kit.
Company Overview ZEDO, Inc., is a leader in ad serving technology solutions worldwide. ZEDO s Proprietary Third Generation Ad Serving technology provides Industry-leading advancements that enable cost effective ad serving products and services. ZEDO supplies customers with the tools and information they need to effectively manage their online advertising activity such as: low cost rich media serving, automatic revenue optimization, precision targeting, efficient trafficking, and much more. ZEDO is a global company with headquarters in San Francisco and offices in Mumbai, Goa and St. Petersburg. More information about ZEDO Ad Serving solutions can be found at http://www.zedo.com Additional Reading API HTML reference will be available shortly.