Introduction to FreeWheel's Open API

The FreeWheel Application Programming Interface (API) is simply another way to access your FreeWheel data - one that makes it easy for third-party and custom tools to access and interact with the service programmatically. This guide should provide everything you need to implement plug-ins or client software to interact with your data in FreeWheel.

Design your plug-ins to the Freewheel APIs using proper protocols: use the cache properly and limit the frequency of your requests. If you have issues with the API, contact us at [email protected].

The FreeWheel APIs v1-v3 are implemented as an XML interface. You should use an HTTP request with an XML file. The response from our servers will return as an XML file. The FreeWheel APIs v4 use JSON by default, but also support XML.

The FreeWheel API is implemented using RESTful best practices.

What can I do with the FreeWheel APIs?

There are many things that you can do with the FreeWheel API. Below are a few examples:

• Create, update, and access agency and advertiser information.
• Create, update, and access campaign and insertion order information.
• Perform various operations on placements.
• Work with MRM or RPM systems

FreeWheel API Concepts

REST Resources in FreeWheel

In REST parlance, everything is considered a resource. There are multiple collections of resources in the FreeWheel API: sites, site sections, video groups, video series, etc. Each collection of resources and each individual resource can be identified by URL and can be operated upon by various methods. Here are some examples:

In FreeWheel, some resource types form a hierarchy structure, such as sites belonging to site sections or videos belonging to video groups. Such nested resources are supported at some levels. Resource-specific details can be found in the resource's specification.

URL Representation

The URL for the API is: https://api.freewheel.tv/services/
If you have access to a staging network, the URL will be: https://api.stg.freewheel.tv/services/

The URLs for the individual interfaces can be found in the specific documentation for that interface.
For example, to get the information for a site with ID 1, the user needs to send a GET request to the URL https://api.freewheel.tv/services/v4/sites/1 to call the "show" method of the Site API v4. In this URL, the final "1" is a mutable parameter. To describe the URL format of API methods, we use "{}" to represent mutable parameters in the URL. So for the "show" method of Site API v4, its URL format is

https://api.freewheel.tv/services/v4/sites/{site_id}

API Authentication

API authentication requires the user to generate an OAuth 2.0 access token. This token expires periodically and must be regenerated if expired. You can find detailed information in the Authentication API.

Requests that exceed the throttling rate of twenty requests per second receive errors.

API Password Reset Policy

If you have access to both MRM and Freewheel's APIs, it is recommended that you reset your password every 180 days. However, API-only user account passwords must be updated within 365 days. If your password expires, you cannot generate OAuth tokens to gain access to Freewheel's APIs.

📘

Note

If users' permissions change, the password expiration policy changes to match their new access level. For example, an API-only user who gains access to MRM and is now a user with access to both MRM and APIs, will need to reset the account password every 180 days.

Changing Your Password

To change your password:

1. Go the User Setup page.
2. Follow the Forgot Password workflow.

📘

Note

If you are unable to receive emails or do not remember the account's password hint, contact the network administrator who will be able to reset email addresses and password hints.

For more information, see the FreeWheel API Password Expiration Policy.

Content Type

The FreeWheel API uses JSON by default for requests and responses, but clients can also use XML. The expected media type is application/json or application/xml. The media type must always be specified in two request headers: Content-Type (the format of the data you're sending) and Accept (the format of the response you want). Otherwise, FreeWheel may not interpret your request correctly, resulting in a 4xx error. Here is an example of specifying content-type with cURL:

curl -X GET
     -H "Content-Type: application/json"
     -H "Accept: application/json"
     -H "Authorization: Bearer MY_OAUTH_ACCESS_TOKEN"
     "https://api.freewheel.tv/services/v4/sites/1"

All XML bodies in the request and response should be XML 1.0. All JSON and XML requests should further be encoded as UTF-8.

Updates and Breaking Changes to the API

As FreeWheel’s APIs are augmented with new features and enhancements, deprecated features are announced in the Release Guide and marked deprecated in their respective documentation. The removal dates for features are indicated in the Release Guide as well.

❗️

Deprecation vs. Removal

Note: Deprecated features still work but no longer receive updates or support. Removed features no longer work and may result in errors if you attempt to use them.

Please update your implementation accordingly as the above changes can break the API schema as it is defined in each interface’s specification.

API Gateway Migration to Amazon Web Services ¶

In order to provide API users with more functionality and greater scalability and reliability, FreeWheel has switched all Open API traffic to the Amazon Web Services (AWS) API gateway.

All Open API traffic coming from V4 endpoints was migrated to the AWS API gatewayby by the 6.30 release (07/02/19).

This switch affects the following endpoints only:

• Ad unit v4

• Creative API v4

• Forecasting v4

• Site v4

• Video V4

What Do I Need To Do for this Migration?

Amazon API Gateway Limits

The Amazon API Gateway has some character limits. For more information, refer to this Amazon documentation.

Freewheel does not need Content-Encoding in HTTP request headers. If you include Content-Encoding in the HTTP request, the Amazon API Gateway may return a 415 Unsupported Media Type error and the error will not be logged. Refer to this Amazon documentation.

Response headers should not be copied into requests. For example, if Amazon API Gateway headers starting with x-amz- or x-amzn- are added into requests, Amazon API Gateway may directly reject the requests, without forwarding to Freewheel.

Programming Notes

Resource Methods

Four standard HTTP methods are supported: GET, POST, PUT, and DELETE. In cURL, the -X option specifies the request method.

• To retrieve an individual resource, use the GET method. For example, to get information of a site with id = 1:

curl -X GET
     -H "Content-Type: application/json"
     -H "Accept: application/json"
     -H "Authorization: Bearer MY_OAUTH_ACCESS_TOKEN"
    "https://api.freewheel.tv/services/v4/sites/1"

• To create a new resource, use the POST method on a resource collection. The body of the request should be a JSON or XML document in the same format as one of the member resources. For example, to create a video group (using cURL's -d option to provide a request body):

curl -X POST
     -H "Content-Type: application/json"
     -H "Accept: application/json"
     -H "Authorization: Bearer MY_OAUTH_ACCESS_TOKEN"
    "https://api.freewheel.tv/services/v4/video_groups" -d
    '{
      "name": "111",
      "external_id": "897",
      "description": "sample video group",
      "customized_metadata": {
        "label1": "value1",
        "label2": "value2"
      },
      "vod_metadata": "vod_metadata_value",
      "metadata": "6584Y65432165",
      "status": "INACTIVE"
    }'

• The PUT method changes existing resources. The body of the request should be a JSON or XML document in the same format as the member resource. For example:

curl -X PUT
     -H "Content-Type: application/json"
     -H "Accept: application/json"
     -H "Authorization: Bearer MY_OAUTH_ACCESS_TOKEN"
    "https://api.freewheel.tv/services/v4/video_groups/234" -d
    '{
      "name": "111",
      "external_id": "897",
      "description": "sample video group",
      "customized_metadata": {
        "label1": "value1",
        "label2": "value2"
      },
      "vod_metadata": "vod_metadata_value",
      "metadata": "6584Y65432165",
      "status": "INACTIVE"
    }'

📘

Updating Existing Resources

When updating existing resources, you must send in all fields associated with the node you are updating. FreeWheel will overwrite any current information with what is sent through the API instead of adding incremental information to what was previously selected. Unless otherwise specified:

• Missing nodes will not update those fields' values
• Empty nodes (such as ) will clear the values for those fields
• Empty attribute nodes (such as <description/>) will clear that field's value

• The DELETE method permanently removes a member resource. For example:

curl -X DELETE
  -H "Content-Type: application/json"
  -H "Accept: application/json"
  -H "Authorization: Bearer MY_OAUTH_ACCESS_TOKEN"
  "https://api.freewheel.tv/services/v4/sites/1"

📘

In some cases, deleting a resource will cascade to related resources. To ensure data integrity, most resources are not allowed to be deleted, including some sites as used in this example.

Data Types

Data types of resource attributes are defined here.

Creatable and Updatable Attributes

Some attributes are creatable and some are updatable, which means they can be included in the document body during creation (POST) and update (PUT) requests, respectively. Including other attributes may yield an error.

Searchable Attributes

For some kinds of resources, several attributes can be searched against using keywords. This is typically done on the collection resource and, if available, will be shown in that resource's specific documentation. Search terms are case-sensitive.

Limits and pagination

For every request asking for a list of resources (index and search methods, usually), there is a limit of 50 resources in the response. If the number of resources is greater than 50, then a pagination parameter can be used to indicate which set you want. Combined with the per_page parameter, you can limit how many resources come back in a single response.
For example, sending a GET request to the URL below will get the first 10 sites.

https://api.freewheel.tv/services/v4/sites?page=1&per_page=10

The Response

HTTP Status Codes

All response codes are included in the HTTP Status response header. Possible status codes in the API response include:

📘

Expect 100-continue problem

Do not add "Expect: 100-continue" in HTTP header, which will lead to a HTTP 417 error. If using cURL, this header will be added by default. Use -H "Expect: " to explicitly remove this header.

📘

Content-Encoding problem

Do not add "Content-Encoding" in HTTP request header, which will lead to a HTTP 415 UNSUPPORTED MEDIA TYPE error.

Success Response Format

• Successful GET requests will get a response with status code 200. The response body will be the content requested by user, in XML format.
• Successful POST requests (e.g., to create a new site) will get a response with status code 201. The header field will include a named Location whose value is the URI of the newly-created resource, and include the JSON or XML representation of the resource in the body of the response.
• Successful PUT requests (e.g., to update an existing site) will get a response with status code 200. The header field will include a named Location whose value is the URI of the newly-created resource, and include the JSON or XML representation of the resource in the body of the response.
• Successful DELETE requests (e.g., to delete an existing site) will get a response with status code 200, and an empty body.
• Successful POST requests and GET requests will always return the FreeWheel ID for the resources requested or created. It is expected that these IDs will be stored by the client for future use against FreeWheel's API.

Error Messages Format

Various errors could occur when using the API because of invalid requests or internal server errors. The HTTP status code in the response will describe briefly what error just happened. The error messages are also represented in the response body and may vary depending on the error. Clients are advised against implementing against any specific error messages as they may be updated to more accurately reflect issues or due to product updates.