API: Introduction

The Trafficspaces API consists of two discrete APIs

• Ad Store API - a read-write HTTP programmatic interface that helps you interact with your ad store.
• Ad Server API - a read-only HTTP interface that helps you to retrieve ads from the ad servers.

RESTful design

Both APIs have been implemented with RESTful design patterns, which means you can interact with the resources in the system using three basic elements:

1. The base URI of the resource, such as https://example.trafficspaces.com/resources/users
2. The MIME type of the data being submitted or requested. This can be either application/json or application/xml.
3. The HTTP verb for the operation such as GET, POST, PUT or DELETE.

Base URI

When you are using the Ad Store API, all your requests should be relative to the URI of your ad store, i.e.

https://<subdomain>.trafficspaces.com/<resource_uri>

However when you using the Ad Server API, all your requests should be relative to the URI of the ad serving system i.e.

http://ads.trafficspaces.net/<resource_uri>

Authentication

See the Authentication guide for more details.

Resources

Through the APIs, you can interact with the following types of resource

Types

Each resource has one or more attributes, where the attribute values conform to one of the following data types

• string - any printable character in the UTF-8 character set.
• integer - any number between -2³¹ and 2³¹-1.
• unsigned - any number between 0 and 2³¹-1.
• double - any number between 2^-1074 and (2-2^-52)·2¹⁰²³.
• boolean - either true or false.
• date must be specified in the YYYY-MM-DD ISO-8601 format e.g. 2010-12-31.
• datetime must be specified in the YYYY-MM-DDThh:mm:ss ISO-8601 format e.g. 2010-12-31T00:00:00+0000. All time zones are relative to the ad store's time zone setting.
• object - a group of key and value pairs in XML or JSON format
• collection - a series of objects in XML or JSON format

Modifiers

Each value in a resource can have one of more of the following access modifiers

• r - the value can be read multiple times
• w - the value can be written at most once. This is usually only when the resource is created.
• a - the value can be amended multiple times throughout the lifetime of the resource.

Response Data

You can request data in XML or JSON format by setting the HTTP Content-Type or Accept headers.

Alternatively, the response format can be inferred from the file extension of the resource requested by the URL i.e. .xml or .json

Request Data

You can send url encoded query parameters data if you are making a GET or DELETE request.

However if you wish to use either the PUT or POST verbs, you must

1. Format your data in either XML or JSON, and
2. Set the appropriate Content-Type header i.e. application/xml or application/json.
   Alternatively, the data format can be inferred from the extension (if any) of the resource URL i.e. .xml or .json

Code Samples

See the API Code Samples & Libraries section for more details.

Debugging

We recommend that you use the Curl command line utility to debug your requests.

For example, to view XML data received from a user request, you can make a call in this format

curl -u <api-user>:<api-key> https://<subdomain>.trafficspaces.com/resources/users/<username>.xml

or also like this alternative format

curl -u acme:abcdefghijklmnopqwsrtuvwzyz https://acme.trafficspaces.com/resources/users/foo.xml

To receive more detailed request and response data, add the --verbose flag to your request to receive even more debugging information.

curl --verbose -u acme:abcdefghijklmnopqwsrtuvwzyz https://acme.trafficspaces.com/resources/users/foo.xml