MetaCDN Web Service API

MetaCDN offers a RESTful, JSON based Web Service interface, allowing you to create and update a MetaCDN user, register your content for distribution on our CDN, register your media (i.e. video) for encoding and delivery, and customise the branding of your media player.

Overview

The aim of this document is to describe the simple and concise HTTP-based RESTful Web Services for MetaCDN.

The table below shows how the standard CRUD convention maps to HTTP methods, and what corresponding functions in MetaCDN they trigger:

The base URL of the HTTP REST API service is http://www.metacdn.com/api/

Using the API, you can:

• Create a MetaCDN User account.
• Register your Content with MetaCDN.
• Register your Media with MetaCDN.
• Register Branding templates to customise your Media delivery.
• Expose your Content and Media meta-data to third party sites via our oEmbed service.

Using the API

The API is designed to be called programmatically from your own user-written code (e.g. Java, Python, Perl, etc.). For testing your interoperability with the MetaCDN API, we have found the following tools useful:

• HTTP Client - A Mac OS X Leopard developer tool for debugging HTTP services by graphically creating & inspecting complex HTTP messages.
• Wiztools.org RestClient - Java (multiplatform) application to test RESTful webservices.
• If you are having difficulty color matching your Branding template to your website, we highly recommend the Rainbow Color Tools Firefox Add-on, which can extract the color scheme from any website's images and CSS.

Authentication

The majority of methods and end-points in the MetaCDN API require authentication. Depending on the end-point and method called, partner or user credentials (username and secret key) are required. Authentication is performed via HTTP Digest access authentication. Additionally, HTTPS (SSL/TLS) is expected to be available shortly. You can test HTTPS right now by using https://metacdn-hr.appspot.com/api/ as the base URL.

HTTP Response Codes and Errors

When using the MetaCDN Web Service API, the system returns an appropriate HTTP response code for every call you make. These can indicate a successful call:

• 200 OK: Call received successfully.
  
• 201 Created: Resource (e.g. user, content) created successfully.
  
• 202 Accepted: Call received successfully, but processing has not yet completed (rather it is occurring in the background).
  

These can also indicate a problem with your API call formatting or credentials:

• 400 Bad Request: Your request was invalid. A reason is returned by the system.
  
• 401 Unauthorized: Your MetaCDN credentials are either missing or incorrect.
  
• 404 Not Found: The URI you requested is invalid or does not exist (e.g. user, content).