MetaPhilter Doc

« TOC

XML-RPC API

As of MetaPhilter 1.4, the XML-RPC interface is now a core component. The method of implementation for MetaPhilter's XML-RPC support is focused on simplicity of expandability. The same system used to parse index templates creates PHP data types from XML-RPC representations.

The default entry point for any supported API is 'xml-rpc.php' located in the MetaPhilter system directory. There is a special-case URL attachment, however.

The numeric ID of a philter is appended to the entry point URL.

For instance, to access the content of Philter #2 in your database, the URL would be http://yourdomain.com/mp/xml-rpc.php/2 (assuming your MetaPhilter system path was 'mp' from the web root)

If no Philter identifier is given, MetaPhilter assumes you want to use Philter #1:

http://yourdomain.com/mp/xml-rpc.php

...is always an entry point for your first Philter.

• Default APIs

  The default MetaPhilter installation has support for the Blogger API, metaWeblog API, and Movable Type API.

  Should an error occur during any operation, a fault methodResponse is returned.

  • Blogger

    For all supported functions of the Blogger API, the appkey and blogid are ignored.

    • blogger.newPost(string appkey,string blogid,string username,string password,string content,boolean publish)

      Creates a new link.

      Returns the string postid of the new link created.

      Note: If publish is false, the link is not posted.

    • blogger.editPost(string appkey,string postid,string username,string password,string content,boolean publish)

      Edits the existing link of ID postid

      Returns a boolean true on success.

    • blogger.deletePost(string appkey,string postid,string username,string password,boolean publish)

      Deletes the link with ID postid

      Returns a boolean true on success.

    • blogger.getPost(string appkey,string postid,string username,string password)

      Returns the link of ID postid.

      Returns a struct containing the members dateTime.iso8601 dateCreated, string userid, string postid, string content.

    • blogger.getRecentPosts(string appkey,string blogid,string username,string password,int recentposts)

      Returns a number of recent links, starting from the most recent in the database.

      Returns an array of structs containing the members dateTime.iso8601 dateCreated, string userid, string postid, string content.

    • blogger.getUserBlogs(string appkey,string username,string password)

      Returns infoformation of the Philter.

      Returns an array of structs containing the members string url, string blogid, string blogName.

    • blogger.getUserInfo(string appkey,string username,string password)

      Returns information of the current user.

      Returns a struct with members string userid, string firstname, string lastname, string nickname, string email, string url.

  • metaWeblog

    For all supported functions of the metaWeblog API, blogid is ignored.

    • metaweblog.newPost(string blogid,string username,string password,struct content,boolean publish)

      Creates a new link.

      The content structure can contain these standard members:

      • title

        Title of the link.

      • description

        Description of the link (not the URL_description). This is a required member.

      Any of the Movable Type's extensions:

      • mt_text_more

        The extended body of the link.

      • mt_tb_ping_urls

        An array of TrackBack URLs to ping while creating the link.

      And any of the MetaPhilter extensions:

      • mp_URL

        The URL of the link.

      • mp_URL_description

        The URL_description of the link.

      Returns the string postid of the new link created.

      Note: If publish is false, the link is not posted.

    • metaWeblog.editPost(string postid,string username,string password,struct content,boolean publish)

      Edits the existing link of ID postid

      The content structure can contain these standard members:

      • title

        Title of the link.

      • description

        Description of the link (not the URL_description). This is a required member.

      Any of the Movable Type's extensions:

      • mt_text_more

        The extended body of the link.

      And any of the MetaPhilter extensions:

      • mp_URL

        The URL of the link.

      • mp_URL_description

        The URL_description of the link.

      Returns a boolean true on success.

    • metaWeblog.getPost(string postid,string username,string password)

      Returns the link of ID postid.

      Returns a struct with members string userid, dateTime.iso8601 dateCreated, string postid, string description, string link, string permaLink, string mt_text_more, string mp_URL, string mp_URL_description.

    • metaWeblog.getRecentPosts(string blogid,string username,string password,int recentposts)

      Returns a number of recent links, starting from the most recent in the database.

      Returns an array of structs containing the members dateTime.iso8601 dateCreated, string userid, string postid, string description, string title, string link, string permaLink, string mt_text_more, string mp_URL, string mp_URL_description.

    • metaWeblog.newMediaObject(string blogid,string username,string password,struct file)

      Uploads a file to your server.

      The file structure must contain a bits member that is the base64 encoded file, and a string name member that is of the target filename.

      Returns the resulting URL of the uploaded file.

      Note: To upload a file, a user must have the 'remote_upload' permission.

  • Movable Type

    For all supported functions of the Movable Type API, blogid is ignored.

    • mt.getRecentPostTitles(string blogid,string username,string password,string recentposts)

      Returns a list of link titles, starting by the most recent in the database.

      Returns a struct containing the members dateTime.iso8601 dateCreated, string userid, string postid, string title.

    • mt.getCategoryList(string blogid,string username,string password)

    Returns a list of postable categories.

    Returns an array of structs containing the members string categoryId, string categoryName.

    • mt.getPostCategories(string postid,string username,string password)

      Returns the category the link of ID postid has been posted in.

      Returns an array of one struct with the members string categoryName, string categoryId, boolean isPrimary

      Note: The isPrimary member is always set to true.

    • mt.setPostCategories(string postid,string username,string password,array categories)

      Sets the category of the link with ID postid.

      The categories array must contain structures with the members string categoryId and an optional boolean isPrimary. If the array contains multiple structures, only the first is used, or the structure with its isPrimary member set true.

      Returns a boolean true.

    • mt.supportedMethods()

      Returns an array of strings, each is a registered API method supported by your Philter.

• Building APIs

  The system that drives all supported XML-RPC APIs are simply classes registered by the xmlRpc class. The xmlRpc object is intended to allow an easy method of supporting new XML-RPC APIs within the same basic XML-RPC request/respone builder.

  • The XML-RPC Class

    The class is defined in the 'rpc.php' file.

    Here's an outline of the methods in the xmlRpc class:

    • server(string $xml)

      Parses the given XML with the MetaPhilter template system and calls the appropriate registered API function with the specified parameters.

    • client(string $url,string $methodName [,mixed $parameter, ... ])

      Connects to a remote XML-RPC server and calls the specified method with the given parameters.

      Each parameter given should be native PHP data or a variable. This function with then serialize each parameter into its appropriate XML-RPC element.

      This function returns native PHP data.

      To use this function to call weblogs.com's XML-RPC pinging service and print the returned message:

      $response=xmlRpc::client('http://rpc.weblogs.com/RPC2',
                               'weblogUpdates.ping',
                               'TurkeyFilter',
                               'http://www.turkeyfilter.com');
      if ($response->flerror) print 'Error: ';
      print $response->message;
      

    • registerAPI([string $class])

      Registers a class's methods as being supported by your xmlRpc::server function.

      If you do you not specify a class name, an associative array with the currently registered APIs is returned. Each key in the array is the name of an API. Its value is an array of function names.

    • fault(mixed $parameter)

      Returns a methodResponse with the fault parameter of the XML-RPC-serialized value of $parameter.

  • Implementation

    The default MetaPhilter installation comes with a basic XML-RPC entry point, 'xml-rpc.php', which uses this class to register supported APIs and call the xmlRpc::server function with the XML sent through the POST method.

    The script includes files in the 'API' subdirectory of your MetaPhilter system path. You should place extra classes there for MetaPhilter to automatically register them as supported APIs.

    Here's an example of a basic XML-RPC service with one API and one supported method:

    <?php
    
      //paragraph.php, the XML-RPC paragraph service
    
      include 'mp/rpc.php';
    
      class paragraph {
        function splitBySentence($paragraph) {
          if (strpos($paragraph,'.')===false) {
            $error=new stdClass;
            $error->faultCode=1;
            $error->faultString='This text contains no sentences!';
            return $error;
          }
          return preg_split('/\.\s*/',$paragraph,-1,PREG_SPLIT_NO_EMPTY);
        }
      }
    
      xmlRpc::registerAPI('paragraph');
    
      xmlRpc::server($GLOBALS['HTTP_RAW_POST_DATA']);
    
    ?>
    

    Here's an example of how to use the new API with MetaPhilter's client API:

    <?php
    
      include 'mp/rpc.php';
    
      $my_paragraph='Sentence one. Sentence two. Sentence three.';
    
      print_r(xmlRpc::client('http://localhost/paragraph.php',
                             'paragraph.splitBySentence',
                             $my_paragraph));
    
    ?>
    

    When executed, that script should return:

    Array
    (
        [0] => Sentence one
        [1] => Sentence two
        [2] => Sentence three
    )
    

    To use the default XML-RPC entry point, you can just a create new file and place it in the 'API' subdirectory of you MetaPhilter system path:

    <?php
    
      //paragraph.php, the XML-RPC paragraph service
    
      class paragraph {
        function splitBySentence($paragraph) {
          if (strpos($paragraph,'.')===false) {
            $error=new stdClass;
            $error->faultCode=1;
            $error->faultString='This text contains no sentences!';
            return $error;
          }
          return preg_split('/\.\s*/',$paragraph,-1,PREG_SPLIT_NO_EMPTY);
        }
      }
    
      xmlRpc::registerAPI('paragraph');
    
    ?>
    

    Now, when 'xml-rpc.php' is requested from the server, the 'paragraph' API is automatically included.