Podcast Machine

Podcastmachine REST XML API

Podcastmachine has a great REST based XML API for managing your podcasts. In time this document will completely document all the features of the API.

The current XML schema for the supported XML structures are defined in http://podcastmachine.com/schemas/api_1_0.xsd

All calls to the API should go to http://podcastmachine.com followed by the path of the resource that you want to access. For more information on the structure of REST URLs please see the section "A Quick Introduction to REST"

A Quick Introduction to REST

InfoQ has a nice short introduction to REST at http://www.infoq.com/articles/rest-introduction. Specificaly you should note that in order to use the XML API you must set your Accept header to application/xml. Alternativly you can add a .xml extension to the URL you are calling which is quite handy for testing the GET based request in a stadard web browser.

Creating an Episode

HTTP method
POST
URL
/podcasts/[podcast_id]/episodes
Document element
episode

Example

If you want to create a new episode for the podcast with id 1 you would send the following request:
 
    POST http://podcastmachine.com/podcasts/1/episodes HTTP/1.1
    Connection: close
    Accept:
application/xml
    Content-Type: application/xml
    Authorization: Basic [INSERT YOUR BASE64 ENCODED AUTH HERE]
    Content-Length: 109
    Host: podcastmachine.com
    
    <?xml version='1.0' encoding='UTF-8'?>
    <episode>
       <title>
My awesome episode</title>
       <description>
The best episode ever!</description>
    </episode>


If all goes right you would receive the following response, telling you that a new episode was created and can be found at http://podcastmachine.com/podcasts/1/episodes/57:
    HTTP/1.1 201 Created
    Connection: close
    Date: Fri, 20 Jun 2008 09:57:22 GMT
    Status: 201 Created
    Location: http://podcastmachine.com/podcasts/1/episodes/57

Adding Media Files to an Episode

HTTP method
POST
URL
/podcasts/[podcast_id]/episodes/[episode_id]/media_files
Document element
media_file

Example

    POST http://podcastmachine.com/podcasts/1/episodes/1/media_files.xml HTTP/1.1
    Connection: close
    Accept:
application/xml
    Content-Type: application/xml
    Authorization: Basic [INSERT YOUR BASE64 ENCODED AUTH HERE]
    Content-Length: 164
    Host: podcastmachine.com
    
    <?xml version='1.0' encoding='UTF-8'?>
    <media_file>
       <url>http://server.com/path/to/video.mp4</url>

    </media_file>

Errors

Things go wrong so you might get some error messages from the API. These error messages are also XML based.


Example

    HTTP/1.1 200 OK
    Connection: close
    Date: Fri, 20 Jun 2008 10:04:59 GMT
    Status: 200 OK
    Content-Type: application/xml; charset=utf-8
    Content-Length: 132

    <?xml version="1.0" encoding="UTF-8"?>
    <errors>
      <error>Title is already used by another episode in this podcast</error>
    </errors>