WordPress XML-RPC – MetaWeblog API

As odd as it may sound, WordPress’ XML-RPC system is built on others.  This makes sense from a development standpoint – why reinvent the wheel when others have done such a great job?  But it can be incredibly confusing and downright frustrating when you start working with the WordPress API and have to turn to metaWeblog’s or Blogger’s documentation to figure something out.

The fragmentation of the API documentation is what turns many off from XML-RPC development at first.  That said, the APIs are stitched together quite elegantly when you look at the server code.  To make things simpler, we’ll deal with one set of API calls at a time.  The most basic are the metaWeblog calls, so we’ll start there.

metaWeblog.newPost

Function: Creates a new post on your blog.

Parameters:

• Blog ID – For use in multisite installations, typically 0 for single sites
• Username – WordPress username
• Password – WordPress password
• Content – Your blog post defined as an associate array with the following fields
  • ‘post_type’ – ‘post’ or ‘page’
  • ‘wp_slug’ – Post slug (optional)
  • ‘wp_password’ – Post password (optional)
  • ‘wp_page_parent_id’ – ID of the parent post (optional)
  • ‘wp_page_order’ – Menu order (optional)
  • ‘wp_author_id’ – Identify an author other than the user posting the request (optional)
  • ‘title’ – Post title
  • ‘description – Post body content
  • post-type_status – Set the post/page/custom status to draft, private, publish, publish, or pending
  • ‘mt_excerpt’ – Post excerpt
  • ‘mt_text_more’ – Text for the Read More link
  • ‘mt_keywords’ – Tags
  • ‘mt_allow_comments’ – Set whether comments are open or closed
  • ‘mt_allow_pings’ – Same settings as ‘mt_allow_comments’
  • ‘mt_tb_ping_urls’ – An array of the URLs you want to ping on publication
  • ‘date_created_gmt’ – The publication date for the post
  • ‘dateCreated’ – Same as above … use one or the other
  • ‘categories’ – An array of categories for the post.
• Publish – The status you want the post to have, either publish or draft

Returns: ID of the post you just created

metaWeblog.editPost

Function: Allows you to update the content of a published post.

Parameters:

• ID of the post you want to edit
• WordPress username
• WordPress password
• Post content (same as for metaWeblog.newPost) – Only send the parameters you want to change.
• Publish – The status you want the post to have, either publish or draft

Returns: True – yup, that’s it.  Just the Boolean value true.

metaWeblog.getPost

Function: Gets the value of a given post on the blog.

Parameters:

• ID of the post you want to retrieve
• WordPress username
• WordPress password

Returns: An associative array of the post content.

• ‘dateCreated’ – Post publication date
• ‘userid’ – ID of the post author
• ‘postid’ – ID of the post itself
• ‘description’ – Post content
• ‘title’ – Post title
• ‘link’ – Post permalink
• ‘permaLink’ – Post permalink
• ‘categories’ – Array of post categories
• ‘mt_excerpt’ – Post excerpt
• ‘mt_text_more’ – Read More text
• ‘mt_allow_comments’ – Whether comments are open or closed
• ‘mt_allow_pings’ – Whether pings are open or closed
• ‘mt_keywords’ – Array of post tags
• ‘wp_slug’ – Post slug
• ‘wp_password’ – Post password
• ‘wp_author_id’ – ID of the post author
• ‘wp_author_display_name’ – Display name of the post author
• ‘date_created_gmt’ – Post publication date (as GMT time)
• ‘post_status’ – Post publication status
• ‘custom_fields’ – Array of custom fields
• ‘sticky’ – Whether or not the post is marked as “sticky”

metaWeblog.getRecentPosts

Function: Gets an array of recent posts on the blog – similar to metaWeblog.getPost, but it returns as many posts as you want.

Parameters:

• ID of the blog you’re working with (usually 0 for a single site)
• WordPress username
• WordPress password
• Number of posts you want to return

Returns: An array where each element of the array is itself an array containing the content of a post.  See metaWeblog.getPost for a description of the post content array.

metaWeblog.getCategories

Function: Gets a list of categories used by the blog.

Parameters:

• ID of the blog you’re working with (usually 0 for a single site)
• WordPress username
• WordPress password

Returns: Returns a simple array, where each element is an associate array defining the category:

• ‘categoryID’ – ID of the category
• ‘parentID’ – ID of the category’s parent
• ‘description’ – Name of the category
• ‘categoryDescription’ – Description of the category
• ‘categoryName’ – Name of the category
• ‘htmlUrl’ – Category permalink
• ‘rssUrl’ – RSS feed for the category

metaWeblog.newMediaObject

Function: Uploads a media file to your blog, based on your media settings.

Parameters:

• ID of the blog you’re uploading to (usually 0 for a single site)
• WordPress username
• WordPress password
• Upload data (array)
  • Upload name
  • File type
  • File bit data (the file itself)

Returns: An array with elements file (file name), url (file url), and type.