How to construct parameters for wordpress xml-rpc call?

WordPress xml-rpc calls are nothing but http post requests. The core stuff is building the body for the post request. The body is an xml containing the information such as method name and method parameters. Let’s see a full xml payload for the metaWeblog.newPost call.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
 <methodName>metaWeblog.newPost</methodName>
 <params>
  <param>
   <value>
    <int>0</int>
   </value>
  </param>
  <param>
   <value>
    <string>admin</string>
   </value>
  </param>
  <param>
   <value>
    <string>password</string>
   </value>
  </param>
  <param>
   <value>
    <struct>
     <member>
      <name>categories</name>
      <value>
       <array>
        <data>
         <value>
          <string>category name</string>
         </value>
        </data>
       </array>
      </value>
     </member>
     <member>
      <name>custom_fields</name>
      <value>
       <array>
        <data>
         <value>
          <struct>
           <member>
            <name>key</name>
            <value>
             <string>_yoast_wpseo_title</string>
            </value>
           </member>
           <member>
            <name>value</name>
            <value>
             <string>meta title</string>
            </value>
           </member>
          </struct>
         </value>
         <value>
          <struct>
           <member>
            <name>key</name>
            <value>
             <string>_yoast_wpseo_metadesc</string>
            </value>
           </member>
           <member>
            <name>value</name>
            <value>
             <string>meta description</string>
            </value>
           </member>
          </struct>
         </value>
        </data>
       </array>
      </value>
     </member>
     <member>
      <name>description</name>
      <value>
       <string>post content</string>
      </value>
     </member>
     <member>
      <name>mt_allow_comments</name>
      <value>
       <int>1</int>
      </value>
     </member>
     <member>
      <name>mt_allow_pings</name>
      <value>
       <int>1</int>
      </value>
     </member>
     <member>
      <name>mt_keywords</name>
      <value>
       <string>keyword</string>
      </value>
     </member>
     <member>
      <name>post_type</name>
      <value>
       <string>post</string>
      </value>
     </member>
     <member>
      <name>title</name>
      <value>
       <string>post title</string>
      </value>
     </member>
    </struct>
   </value>
  </param>
  <param>
   <value>
    <boolean>1</boolean>
   </value>
  </param>
 </params>
</methodCall>

Note that there is only one top level element <methodCall>. The top-level element has two sub-elements:<methodName> and <params>. <params> can have multiple child elements <param>. Each <param> has only one child: <value>. Note that there is no child element <name> for the <param>, which means <param> has not a name and you should arrange the parameters in strict order as in the specification. If you miss a required parameter or parameters are not in the wanted order, the call will fail. <value> has various types, represented in different tags under <value>. But each <value> only has a single child element. The types of <value> are:

int

<value>
   <int>1</int>
</value>

 boolean

<value>
 <boolean>1</boolean>
</value>

 string

<value>
 <string>admin</string>
</value>

 struct

<value>
 <struct>
  <member>
   <name>key</name>
   <value>
    <string>_yoast_wpseo_metadesc</string>
   </value>
  </member>
  <member>
   <name>value</name>
   <value>
    <string>meta description</string>
   </value>
  </member>
 </struct>
</value>

The struct is kind of special. It has multiple <member> children. Each <member> has a <name> child and a <value> child. Since every member in a struct has a name, the order of members is not important because they can be differentiated by their names.

array

<value>
  <array>
    <data>
      <value>
      </value>
      <value>
      </value>
      ...........
    </data>
  </array>
</value>

Array is a little complicated. It has one child: <data>. The <data> child, however, can have many <value>  children. And the <value> children may have different types.

Here is the  xml-rpc parameter specification. Now you should know how to build the xml from given parameters.

The response of an xml-rpc call is simpler. The http response code for an xml-rpc call is always 200 regardless of success or failure.  The content part of the 200 http response is also an xml. The xml has two types, for the successful execution and the failed execution of the call, respectively.

Success

<?xml version="1.0"?>
<methodResponse>
   <params>
      <param>
         <value><string>may be complex struct</string></value>
      </param>
   </params>
</methodResponse>

The top-level element <methodResonse> has a single child <params> which has a single child <param> which has a single child <value>. The <value> may be a complex type so complicated response content can be returned.

Failure

<?xml version="1.0"?>
<methodResponse>
   <fault>
      <value>
         <struct>
            <member>
               <name>faultCode</name>
               <value><int>4</int></value>
            </member>
            <member>
               <name>faultString</name>
               <value><string>Too many parameters.</string></value>
            </member>
         </struct>
      </value>
   </fault>
</methodResponse>

The top-level element <methodResonse> for the failure response has one child <fault> which has one child <value>. The <value> is of <struct> type which has one member called faultCode and another member called faultString.

Comments are closed, but trackbacks and pingbacks are open.