Documentation: services/blog.php

services/blog.php - Process remote blog calls

This script interfaces YACS with popular weblog client software.

The support of the XML-RPC API in YACS is really straightforward. The main complexity is that different words are used for same things. Therefore, please keep in mind that metaWeblog' blogs are YACS sections.

At the moment YACS supports following XML-RPC flavors:

the Movable Type API
the MetaWeblog API
the Blogger API

Actually, all three of those API's build on each other. Blogger is the most basic. MetaWeblog "embraces and extends" it. The Movable Type API does the same to MetaWeblog.

Error codes

YACS uses standard error codes, as specified in Specification for Fault Code Interoperability: "As the number of xml-rpc server implementations has proliferated, so has the number of error codes and descriptions. The charter of this specification is to define a small set of error codes that are common across most server implementations so that clients can programmatically handle common errors such as "method not found" or "parse error"."

Here are the error codes and their meaning:

-32700 ~~-> parse error. not well formed~~
-32701 -> parse error. unsupported encoding
-32702 ~~-> parse error. invalid character for encoding~~
-32600 -> server error. invalid xml-rpc. not conforming to spec.
-32601 ~~-> server error. requested method not found~~
-32602 -> server error. invalid method parameters (bad login, etc.)
-32603 ~~-> server error. internal xml-rpc error (no response)~~
-32500 -> application error (database error)
-32400 ~~-> system error~~
-32300 -> transport error

The Movable Type API

mt.getRecentPostTitles

Returns a bandwidth-friendly list of the most recent posts in the system.

Syntax: mt.getRecentPostTitles(blogid, username, password, numberOfPosts) returns struct

Following components of the struct are correctly processed:

dateCreated - ISO 8601
userid
postid
title

mt.getCategoryList

List all categories defined in the weblog.

Syntax: mt.getCategoryList(blogid, username, password) returns struct

In YACS categories are shared at the system level, therefore the blogid parameter is not used. Returns up to 30 YACS categories.

Returns following components:

categoryId - id of the category
categoryName - the name of the category

mt.getPostCategories

List all categories to which the post is assigned.

Syntax: mt.getPostCategories(postid, username, password) returns struct

Returns following components:

categoryId - id of the category
categoryName - the name of the category
isPrimary - 1 if true, 0 otherwise

mt.getTrackbackPings

List pages linked to this post.

Syntax: mt.getTrackbackPings(postid) returns struct

Returns following components:

pingTitle - title of the entry sent in the ping
pingUrl - the URL of the entry
pingIP - the IP address of the host that sent the ping

mt.publishPost

Publish (rebuild) all of the static files related to an entry from your weblog. Equivalent to saving an entry in the system (but without the ping).

Syntax: mt.publishPost(postid, username, password) returns boolean

mt.setPostCategories

Assign categories to a post.

Syntax: mt.setPostCategories(postid, username, password, struct) returns boolean

The struct has following components:

categoryId - id of the category
isPrimary - 1 if true, 0 otherwise (option)

mt.supportedMethods

Retrieve information about the XML-RPC methods supported by the server.

Syntax: mt.supportedMethods() returns array of strings

The MetaWeblog API

The MetaWeblog API is a programming interface that allows external programs to get and set the text and attributes of weblog posts. It builds on the popular XML-RPC communication protocol, with implementations available in many popular programming environments.

The MetaWeblog API uses an XML-RPC struct to represent a weblog post. Rather than invent a new vocabulary for the metadata of a weblog post, this uses the vocabulary for an item in RSS 2.0. So you can refer to a post's title, link and description; or its author, comments, enclosure, guid, etc using the already-familiar names given to those elements in RSS 2.0.

metaWeblog.editPost

Modify or publish an existing post.

Syntax: metaWeblog.editPost(postid, username, password, struct, publish) returns true

Following components of the struct are correctly processed:

title - set the page title
source (a sub-component of the 'description' field) - set the page source, usually, an originating URL
introduction (a sub-component of the 'description' field) - set the page introduction
description - set the actual page content
category - link this page to listed categories

If the publish field is set to TRUE, the publication mechanism of YACS applies.

metaWeblog.deletePost

An alias for blogger.deletePost

metaWeblog.getCategories

List categories for a given blog.

Syntax: metaWeblog.getCategories(blogid, username, password) returns struct

In YACS categories are shared at the system level, therefore the blogid parameter is not used. Returns up to 30 YACS categories.

Returns following components:

categoryId - id of the category
categoryName - the name of the category
description - category description
rssUrl - reference of the RSS feed for the category
htmlUrl - reference of the category web page

metaWeblog.getPost

Read one post. Returns the post if successful, or a fault otherwise.

Syntax: metaWeblog.getPost(postid, username, password) returns struct

Returns following components:

title - page title
link - the web address to get the original page
permaLink - the web address to get the original page
description - the actual page content - with 'introduction' and 'source' sub components
author - mail address of the page creator
comments - the web address to comment the page
dateCreated - date of last edition (ISO 8601)
userid - id of last editor
postid - page id

Six Apart extensions: String mt_excerpt, String mt_text_more, int mt_allow_comments, int mt_allow_pings, String mt_convert_breaks, String mt_keywords;

metaWeblog.getRecentPosts

List most recent posts at a given blog.

Syntax: metaWeblog.getRecentPosts(blogid, username, password, numberOfPosts) returns array of structs

Each post has following components:

dateCreated - date of last edition
userid - id of last editor
postid - page id
title - page title
link - the web address to get the original page
permaLink - the web address to get the original page
description - the actual page content - with 'introduction' and 'source' sub components
author - mail address of the page creator
comments - the web address to comment the page
pubDate - publication date, if any
category - list of related categories, if any

Returns up to 30 posts from the target blog.

metaWeblog.getUsersBlogs

An alias for blogger.getUsersBlogs

metaWeblog.getTemplate

An alias for blogger.getTemplate

metaWeblog.newMediaObject

Upload some file to a blog. If successful, the method will return a URL to the newly created file. Otherwise, a fault will be returned.

Please note that the data model with this API is to attach files to the blog, where YACS offers to attach files to final pages.

Syntax: metaWeblog.newMediaObject(blogid, username, password, struct) returns struct

The submitted struct has following attributes:

name - file name
type - media type of the file (e.g., text/html) - can be safely ignored
bits - the base64-encoded contents of the file

The returned structure has only one attribute:

url (to be used to access uploaded file)

metaWeblog.newPost

Create a new post, and optionally publishes it. If the post is successful, this method will return the id assigned to the post by the server. Otherwise, it will return a fault.

Syntax: metaWeblog.newPost(blogid, username, password, struct, publish) returns string

Following components of the struct are processed:

title - set the page title
source (a sub-component of the 'description' field) - set the page source, usually, an originating URL
introduction (a sub-component of the 'description' field) - set the page introduction
description - set the actual page content
categories - link this page to listed categories

If the publish field is set to TRUE, the publication mechanism of YACS applies.

metaWeblog.setTemplate

An alias for blogger.setTemplate

The Blogger API

blogger.deletePost

Definitely suppress an existing post. Method will return true if successful or a fault otherwise.

Syntax: blogger.deletePost(ignored_appkey, postid, username, password) returns boolean

blogger.editPost

Modify or publish an existing post. If the request is successful then the method will return true, otherwise it will return a fault.

Syntax: blogger.editPost(ignored_appkey, postid, username, password, content, publish) returns boolean

The content field can include following HTML tags:

source - set the page source, usually, an originating URL
introduction - set the page introduction

If the publish field is set to TRUE, the publication mechanism YACS is correctly used

blogger.getPost

Read one post.

Syntax: blogger.getPost(ignored_appkey, postid, username, password) returns struct

Returns following components:

dateCreated - date of last edition
userid - id of last editor
postid - page id
content - the actual page content - with 'introduction' and 'source' sub components

blogger.getRecentPosts

Retrieves a list of posts that were created recently in a blog. The results are returned in descending chronolocial order with the most recent post first in the list.

Syntax: blogger.getRecentPosts(ignored_appkey, blogid, username, password, numberOfPosts) returns array of structs

Returns up to 30 posts of the mentioned blog.

Each returned post has following components:

dateCreated - date of last edition
userid - id of last editor
postid - page id
content - the actual page content - with 'introduction' and 'source' sub components

blogger.getTemplate

Read one template.

Syntax: blogger.getTemplate(ignored_appkey, blogid, username, password, template_type) returns string

Template type can be either 'main' or 'archiveIndex'.

If the target section does have a template attribute, it is returned to caller. Else a bare and simple template is returned instead.

blogger.getUserInfo

If the user specified by the supplied username and password is found, then the method returns information about that user, specifically: the user

Browse the source of this script · Server software