This document describes an API for authoring and publishing podcasts on Mevio. Comment here.
- 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:
| title | The podcast episode name. (string) |
| subtitle | The podcast episode subtitle. (string) |
| pubDate | The publish date for the podcast episode. May be in the future. (RFC822 date) |
| isExplicit | Whether the episode contains explicit language. (boolean, true or false) |
| summary | A short version of what the episode is about. (string) |
| description | Shownotes. (string) |
| tags | Comma-separated list of tags for the episode. (string) |
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:
- An enclosure element in the struct
- The link element
- 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
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!
by Andrew Grumet on 3 Apr 2006
Posted for public comment on 21 Jul 2006
API Last Updated on 4 Jul 2006