Getting Started with the API: The Web Services

First off, we'd like to thank everyone for the feedback thus far; we will continue to incorporate it as we plan new features for the API. We are also very excited about the applications we've seen being built and would love to hear more about them on our forum.

Today, in the first part of our Getting Started with the API series, I'd like to discuss some of the more technical aspects of the API. As many of our developers are just getting started with the API, I'd like to remind everyone that we provide a full documentation site, and much of the following information is taken from there. I'd also like to point out that if at any time you feel we could better document a feature or expand on a detail, please do not hesitate to leave any suggestions on our feedback survey. 

General service overview

As you have most likely determined by now, our API uses SOAP and provides one WSDL per service. The output from code generation on each WSDL can be combined to create the complete API; this is currently what we are doing in the client libraries.

Our API is versioned and, because objects are separated into namespaces according to their version, objects from one version will not work with any other version. We will support multiple versions of the API at the same time - both in our documentation and in our client libraries. Our versioning timeline has not yet been determined, but each version will have at least a 4 month sunset period before it is disabled.

Our API is highly consistent; each service has the same methods:

• createObject
• createObjects
• getObject
• getObjectsByFilter
• performObjectAction
• updateObject
• updateObjects

* Note here that these methods are examples where Object would be replaced, by Order or LineItem.

In each service, all methods act on a single type of Object. For example, the OrderService only provides methods to create, get, or update orders; i.e. getOrdersByFilter and updateOrders. This allows you to develop a standard way of handling service invocation in your application; you will always call getObjectsByFilter, but the filter may change depending on the service, and it will always return some type of Page.

For creating objects, we provide two methods that are interchangeable - createObject and createObjects; createObjects is simply a convenience method that performs the same task as createObject.

To create an object, a local object is created with all the required fields and passed via one of the mentioned methods. The returned object will be the result of this creation. It will have its defaults filled in and its ID populated.

For getting objects, we provide two methods - getting an object by its ID and getting objects by a PQL statement. In cases where you might want to get the most recent version of an object quickly, getObject would suffice. Retrieving large sets of information for the user would call for paging through a series of getObjectsByFilter service calls.

The final methods involve mutating objects on our server. The update methods provide a way of performing an object replacement by its ID. A typical workflow for updating an object given user input would resemble the following steps:

1. Perform a getObjectsByFilter call and present the user with a large set of data.
2. After the user selects one particular object, perform a getObject call by recalling its ID.
3. The user modifies the object to update it locally; the ID should not change.
4. Finally, perform an updateObject call, passing in the full updated object.

Notice that in our general workflow, getObject must be called before the updateObject call so that the most recent version of the object is modified.

The last method, performObjectAction, allows you to specify an action that takes place on the objects selected by the supplied filter. Instead of returning a set of objects to the developer, who would then typically update them, all updates occur server-side. The performObjectAction methods are mostly used to update the workflow of objects, such as approving or activating them.

As we develop new features for the API, we will continue to keep the consistency we have incorporated so far. As always, we look forward to discussing our API with you on our forum.

-- Adam Rogal, The DoubleClick for Publishers API Team