webservices

Service Document

by Administrator on ‎03-25-2011 10:05 AM

The service document describes the resources available for a particular account. Each Constant Contact account has its own service document because the resources available may vary depending on which applications the account uses and what permissions have been granted to the application using the API.

 

The service document is retrieved by issuing an HTTP GET to the account's Base URI. The Base URI is http://api.constantcontact.com/ws/customers/{UserName}/ , where {UserName} is the account owner's Constant Contact user name. The {UserName} value must be in lower case, and any character(s) that are not permitted in a URI must be escaped. (Most languages/platforms have a function to do the escaping; in Javascript, it's encodeURIComponent(), in .NET, it's System.Web.HttpUtility.UrlEncode(), in PHP it's urlencode() and in Java, it's java.net.URLEncoder.encode().)

 

Example

 

Here is a service document for an account with the user name joesflowers. This document could be retrieved by doing an HTTP GET on https://api.constantcontact.com/ws/customers/joesflowers/ and presenting the proper credentials:

 

<?xml version='1.0' encoding='UTF-8'?>
<service xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom">
<workspace>
<atom:title type="text">Constant Contact Web Services Customer Workspace</atom:title>
<collection href="/ws/customers/joesflowers/lists">
<atom:title type="text">Contact Lists</atom:title>
<accept>application/atom+xml; type=entry</accept>
</collection>
<collection href="/ws/customers/joesflowers/activities">
<atom:title type="text">Bulk Activity</atom:title>
<accept>application/x-www-form-urlencoded</accept>
<accept>multipart/form-data</accept>
</collection>
</workspace>
</service>

In Atom terminology, a service document describes a Workspace. This one describes the Constant Contact Web Services Customer Workspace. This workspace contains two Collections, called Contact Lists and Bulk Activity. For each collection, the href attribute specifies the collection's URI and the accept element(s) specify the type(s) of documents the collection will accept when creating a new entry. Section 8 of RFC 5023 describes the format of a service document in detail. The documentation page for each collection type will describe the detailed HTTP request and response formats.