Getting Started with the FreeWheel APIs

Introduction

The FreeWheel Application Programming Interface (API) is a service that allows third-party tools to programmatically access and interact with FreeWheel data. This guide outlines requirements for integrating client software with FreeWheel APIs.

Use FreeWheel APIs to:

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

For help with authentication, see Getting Started with Authentication.

For the complete API Reference, see API Reference.

Design Resources

When designing plug-ins to the Freewheel APIs, be sure to utilize the cache and limit request frequency to 20 requests/second. Exceeding the throttling rate of twenty requests per second will result in failed calls.

Content Type

FreeWheel V1-V3 APIs use XML. These APIs only accept HTTP requests with XML files. Responses from our servers will return in XML.

FreeWheel V4 APIs use JSON , with XML support for select V4 APIs. Responses from our servers will return in the same language as the requests.

Media Type

The expected media type is application/json or application/xml, depending on which language the API supports. The media type must always be specified in two request headers:

  1. Content-Type for the format of the data you're sending
  2. Accept for the format of the response you want. Otherwise, FreeWheel may not interpret your request correctly, resulting in an error.
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.

Resources

REST Resources

In REST, 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:

URLHTTP MethodRequest BodyAPI ResourceDescription
https://api.freewheel.tv/services/v4/sites/{site_id}GETn/asite_idGet information about site with id=1
https://api.freewheel.tv/services/v4/sitesPOSTJSON or XML bodysitesCreate a new site resource with the provided data in the request body

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

URLs


Production URL
https://api.freewheel.tv/services/v4/services

Staging URL
https://api.stg.freewheel.tv/services/v4/services

To see the URI for a specified API, visit the API in the API Reference.

Authentication

API authentication requires the user to generate an OAuth 2.0 access token. This token expires periodically and must be regenerated if expired. For details on authentication, see Getting Started with Authentication.

Passwords

If you have access to both MRM and Freewheel APIs, we recommend password resets every 180 days. However, API-only user account passwords only require password resets every 365 days.

If your password expires, you cannot generate OAuth tokens to gain access to Freewheel's APIs.

ScenarioReset Procedure
Users with MRM and API accessReset your passwords every 180 days in order to maintain access to the MRM UI and API Access
Users with API access onlyReset your passwords every 365 days in order to maintain API access.

📘

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 will be required to do a password reset every 180 days.

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

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 your network administrator.


Updates and Breaking Changes

FreeWheel announces all API changes in Release Guides.

Deprecated/removed features will be indicated in the Release Guide and marked deprecated/removed in their respective documentation.

🚧

Deprecation vs. Removal

Deprecated features still work, but no longer receive updates or support. Removed features no longer work and may result in errors when used.

Please update your implementation accordingly when deprecated or removed features are announced, as the changes can break client tools that interpret API schema.

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.

AWS Gateway Restrictions

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, but can be deactivated.

Data Types

Data types of resource attributes are defined here.

NameDeclaration ExampleNote
StringString
Boolean'TRUE', 'FALSE'
DatetimeDateTimeUnless otherwise specified, datetime values are expected and given in the ISO 8601 standard format "YYYY-MM-DDTHH:MM:SSZ". (See https://en.wikipedia.org/wiki/ISO_8601 for details.)
DateDateUnless otherwise specified, date values are expected and given in the ISO 8601 standard format "YYYY-MM-DDZ". (See https://en.wikipedia.org/wiki/ISO_8601 for details.)
Enumeration['A', 'B', 'C']
IntegerInteger
DecimalDecimalUnless otherwise specified, this indicates space for 2 decimal places (such as 3.14) .
TextTextThis is for a large amount of text. CDATA can be used 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:

CodeResponse MessageMeaningDescription
200OKUpon a successful GET, PUT, or DELETE request.
201CreatedUpon a successful POST request (create method).
401UnauthorizedIncorrect, missing, or invalid access credentials
403'*' not a valid key=value pair (missing equal sign) in Authorization header: '**'.ForbiddenFreewheel does not support this API. Change the HTTP Method or URL before retrying.
403Missing Authentication TokenForbiddenFreewheel does not support this API. Change the HTTP Method or URL before retrying.
403User is not authorized to access this resource with an explicit denial.ForbiddenThe user does not have permission to access this API.

Contact FreeWheel at [email protected] to get permission for the user.
404Not FoundThe resource you requested is not available
405Method Not AllowedA request was made of a resource using a request method not supported by that resource. For example, using GET on a method which requires data to be sent by POST, or using PUT on a read-only resource.
408Request TimeoutTimeout when processing this request, usually caused by concurrent requests of exclusive access to certain resources. It is recommended that you retry the request.
422Unprocessable EntityInvalid resource. This error happens when the request body is invalid, or the created/updated resource is invalid.
415UNSUPPORTED MEDIA TYPEThe format problem might be due to the request's indicated Content-Type or Content-Encoding, or as a result of inspecting the data directly.
500Internal Server ErrorAPI system error. Contact FreeWheel at [email protected].

📘

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.


What’s Next

Get an understanding of Freewheel's authentication workflow and then visit the API References for information on endpoints and code samples.