Access, Authentication, and Authorization

The Revenue API for News Publishers is available to all Apple News publisher accounts that have access to News Publisher tools on iAd Workbench.

Client side SSL certificate is used to authenticate the user. An access token provides authorization to all of the API.

To access the iAd server, you can request and download the required API keys, tokens, and certificates from the iAd Workbench site.

1. Click on the dropdown arrow next to your account name near the top right and choosing Account from the dropdown menu.

2. Select the API tab under the page title.

3. Click the button to “Create Key”.

4. Name your key and assign access to a tool set.

5. Confirm and download your key in a ZIP file.

You will receive:

• a client-side SSL certificate signed by iAd

• a client-side SSL private key

• an access token

Use the client side SSL certificate, key, and access token when you call the InitSession method. This call authenticates, establishes a secure connection, and provides the session ID required to make further API calls.

As a security measure, three successive invalid authentication attempts will lock the API access for a minimum of four hours.

API Endpoint

Implement your API-based app by following the API Method Reference in this document and use the following end point URL:

• The end point URL used for the Revenue API for News Publishers is https://iadapi.apple.com/publisher/revenue/v1.

This document describes the /v1 version of the iAd News Publishers API.

API Basics

• The iAd News Publishers API supports JSON-RPC 2.0 payloads over HTTP POST. This allows you to create and update campaigns, lines, and ads programmatically.

• A request is a JSON-RPC 2.0 payload in an HTTP POST request with the Content-Type header of “application/json”.

• A response is a JSON-RPC 2.0 payload in an HTTP response request with the Content-Type header of “application/json” and is encoded as UTF-8.

• The request payload contains the method name and the method parameters, which in this API is a single Dictionary object.

• The response payload contains the result, which in this API will be a single Dictionary object.

• Any Array or List should contain uniform types. When an object contains sub-objects, it is referred to as a Collection. Within the JSON-RPC Dictionary objects, all keys must be String objects and the following primitives and objects may be represented (in nested forms): String, Number, Array, Dictionary, Boolean, NULL. For example, an Array may contain String objects, Number objects, other Array objects, or other Dictionary objects, which in turn may have other primitive types within them. Dictionary objects may have any primitive type for a given value, but the keys must be strings.

Versioning of the API

Versioning is managed through the URL. When new features are added to the iAd News Publishers API, as long as they are backward compatible, the URL will remain the same. If new features are added that are not backward compatible, a new URL will be introduced that supports those features and the unchanged features.

Invoking the API

• There is no additional charge to use the Revenue API for News Publishers. However, there is a limit of 10,000 API calls per day (Midnight to Midnight, UTC), total for all iAd APIs. If you expect to make more API calls than this, contact the iAd team through the iAd Workbench “Contact Us” page.

• Because the communication protocol for the Revenue API for News Publishers is JSON RPC 2.0, any language that can perform HTTP get and put can be used to develop client programs.

• Request objects must follow the JSON-RPC 2.0 specification and must include the following fields:

  • jsonrpc: A string specifying the version of JSON-RPC protocol. The string value must be exactly “2.0”.

  • method: A string containing the name of the method to be invoked.

  • id: A unique identifier established by your client program. It must be a string that ideally is unique for each call. The server will reply back using the same ID. If the input request id is unique, the output response will be uniquely assoctiated with the call that generated it. This field must be specified.

  • params: An array of name-value pairs of named parameters and their corresponding values.

• Response objects follow the JSON-RPC 2.0 specification and include the following fields:

  • jsonrpc: A String specifying the version of JSON-RPC protocol, which is exactly “2.0”.

  • id: This will be provided in every response and is the same as the ID sent in the request object.

  • result: In almost all cases, the result includes a Success attribute, a boolean value of true or false indicating success or failure of the API call. If Success is true, then result includes the response to the method request. If Success is false, then result includes an error message and an error code.

API Concepts

This section provides brief descriptions of the API interaction process and workflow phases, at a conceptual level.