C.C. Chapman on the goodness of Kevin Smith.

• Summary
• API Access URL
• Displaying Users Editable Shows
• Uploading Media Episode
• Optional Fields to Publish
• Episode Creation
• Sending Extended Metadata in Struct
• Sending Extended Metadata in Description
• Editing Episodes
• Deleting Episodes
• Featured Products Using API

One Sentence Summary

The authoring API is a special case of the metaWeblog API wherein podcast files are uploaded via newMediaObject and routed to the enclosure element of a newly created RSS item.

It’s XMLRPC

The authoring API is implemented as XMLRC (XMLRPC info). The API access URL is:

http://www.mevio.com/xmlrpc/pdn

Displaying a List of Shows User Can Edit

To display a list of shows that the user can edit make the following XMLRPC call:

blogger.getUsersBlogs(appkey, username, password)

• returns array of structs
• appkey, username and password are strings.
• The PDN ingores appkey, just pass an empty string.
• Each struct in the returned array contains three members: url, blogid and blogName. All are strings. The url is the show’s home page. blogid is used for making calls to metaWeblog.newPost, metaWeblog.newMediaObject and metaWeblog.getRecentPosts. blogName is used to display the name of the show in the authoring tool’s GUI, for choosing what show to post to (e.g. a selectlist).

Docs: http://www.blogger.com/developers/api/1_docs/xmlrpc_getUsersBlogs.html.

Uploading Episode Media

Episode media, e.g. mp3 files, are uploaded by making the following XMLRPC call:

metaWeblog.newMediaObject (blogid, username, password, struct)

• returns struct
• The blogid, username and password are strings
• Values for blogid are usually derived from a previous call to blogger.getUsersBlogs
• Each blogid corresponds to a show_id on Mevio
• The struct must contain the following standard members required by newMediaObject: name, type, bits
• The struct may contain additional members as described in the following section
• The returned struct contains two members, url and postid. The first is the url of the uploaded media. The second member, postid, is the id of the podcast episode for the newly uploaded media.
• The episode may or may not be published at upload time, as described below
• Both url and postid are strings. url is the standard return argument for newMediaObject, while postid is specific to the authoring API.

Docs: http://www.xmlrpc.com/metaWeblogApi#basicEntrypoints
http://www.xmlrpc.com/metaWeblogApi#metaweblognewmediaobject

Optional Struct Fields for Single Call Publishing

The authoring API also accepts the following optional struct fields to permit episode creation and publishing with a single call to newMediaObject:

The string fields should be plaintext with the exception of description, which should contain entity-encoded HTML.

If the struct contains the optional title field, the PDN will assume that the client is performing a single call, and publish the episode. If not, the PDN will not publish the episode, in anticipation of a follow-on call to metaWeblog.newPost.

Episode Creation with metaWeblog.newPost

Standard blog authoring tools may use metaWeblog.newPost to annotate and publish a media file that was uploaded with metaWeblog.newMediaObject.

metaWeblog.newPost (blogid, username, password, struct, publish)

• returns string

The PDN will search for the media file’s url in three places, in the following order:

1. An enclosure element in the struct
2. The link element
3. The description element

The URL returned by newMediaObject must be present in one of these places in order for this method to work correctly.

Docs: http://www.xmlrpc.com/metaWeblogApi#basicEntrypoints
http://www.xmlrpc.com/metaWeblogApi#theStruct

Sending Extended Metadata in the Struct

In addition to the standard title, link and description, the PDN accepts a number of optional struct elements: subtitle, isExplicit, summary, tags. When using newPost and editPost, these fields should be transmitted in the following namespace:

http://developer.podshow.com/apis/pdn/authoring

Docs: http://www.xmlrpc.com/metaWeblogApi#transmittingElementsFromNamespaces

Sending Extended Metadata in the Description Field

For compatibility with existing metaWeblog tools, the authoring API supports inline transmission of the optional elements embedded in the standard description field. These are specified in the description by enclosing them between pipe (|) symbols and demarcating the field names with colons:

Here is an example of how to embed extra fields in a description.
|SUMMARY: Example of extra field embedding.|SUBTITLE: For tool devs.|EXPLICIT: true|TAGS: metaWeblog,authoring,api|

Editing an Episode

Episodes are edited via metaWeblog.editPost, using the postid returned by newMediaObject or newPost.

metaWeblog.editPost (postid, username, password, struct, publish)

• returns string

Docs: http://www.xmlrpc.com/metaWeblogApi#basicEntrypoints
http://www.xmlrpc.com/metaWeblogApi#theStruct

Deleting an Episode

Episodes are deleted via blogger.deletePost, using the postid returned by newMediaObject or newPost.

blogger.deletePost (appkey, postid, username, password, publish)

• returns true

Docs: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msnspaces/MetaWeblogAPI_deletePost_Method.asp

Products Known to Work with the Authoring API

Any tool that supports the metaWeblog API and in particular the newMediaObject call should work with the PDN. That includes blogging tools that pre-date podcasting, such as Ecto. Please help us grow the list!

• Castblaster
• Ecto
• Ubercaster
• Vidblaster

by Andrew Grumet on 3 Apr 2006
Posted for public comment on 21 Jul 2006
API Last Updated on 4 Jul 2006