We will be closed on Monday 1st September for the Labor Day holiday. Support will still be available via the client area although responses may be delayed.
Logo

Help Center

Guides


XML-RPC API

Guide added by Charles Warner, Nov 24 2009 10:15 AM (Updated Nov 12 2012 01:40 PM)



The XML-RPC API allows developers to make XML-RPC calls to IP.Board for information. These tools are for developers only; most users can ignore these features. The following remote APIs are available through the XML-RPC interface:
  • Fetch information regarding the current online users
  • Fetch statistics, including most users online, date most users were online, total number of posts, total number of members, most recent member ID and username
  • Fetch board technical details, including version, "long" version, upload URL, board name and images URL
  • Post a new topic
  • Post a topic reply
  • Fetch details about a member
  • Verify a member exists based on a search (valid searchable fields: id, username, display name, email address)
  • Fetch a select menu of available forums
  • Fetch data about all guest-available forums
  • Fetch a list of topics based on given parameters

Developers wishing to make use of the XML-RPC API will first need to enable the system and create a user, which can be done from Admin CP --> System --> API Users and is discussed in this article. When a user is created, a unique API key is assigned which will be required to make XML-RPC API calls. This user key can be tied to an IP address for additional security if desired.

IP.Board ships with an excellent XML-RPC library that you can utilize to facilitate calls to, and reading responses from, our XML-RPC API. Our license does not permit you to redistribute this file, however you should feel free to copy it to any other location on your site and make use of it as needed. This library functions independently from IP.Board.


Making Calls

You should submit XML-RPC calls to the interface/board/index.php file. You should send all parameters as a struct.

Every request submitted must include at least these two parameters:
  • api_key - this is the key assigned by IP.Board to the API user created previously
  • api_module - this should be "ipb". Theoretically, you can create other modules, but "ipb" is the only one that ships with IP.Board.

IP.Board will check these parameters and then forward the request to the requested method. Other parameters may be required by the individual method, as outlined below:
  • fetchOnlineUsers
    • No additional parameters
  • fetchStats
    • No additional parameters
  • helloBoard
    • No additional parameters
  • fetchStats
    • No additional parameters
  • postTopic
    • member_field: This should be the field to look up the 'member_key' in (for instance, 'member_id', 'email', 'members_display_name', etc.)
    • member_key: The value to search in 'member_field' with in order to find the poster. You may pass member_field as ID and member_key as 1, for instance, to post a topic as member ID 1.
    • forum_id: The ID of the forum to post the topic in
    • topic_title: The topic title
    • post_content: The contents of the first post
  • postReply
    • member_field: This should be the field to look up the 'member_key' in (for instance, 'member_id', 'email', 'members_display_name', etc.)
    • member_key: The value to search in 'member_field' with in order to find the poster. You may pass member_field as ID and member_key as 1, for instance, to post a reply as member ID 1.
    • topic_id: The ID of the topic to post the reply in
    • post_content: The contents of the first post
  • fetchMember
    • search_type: This should be the field to look up the 'search_string' in (for instance, 'member_id', 'email', 'members_display_name', etc.)
    • search_string: The value to search in 'search_type' with in order to find the member. You may pass search_type as ID and search_string as 1, for instance, to fetch details for member ID 1.
  • checkMemberExists
    • search_type: This should be the field to look up the 'search_string' in (for instance, 'member_id', 'email', 'members_display_name', etc.)
    • search_string: The value to search in 'search_type' with in order to find the member. You may pass search_type as ID and search_string as 1, for instance, to check if member ID 1 exists.
  • fetchForumsOptionList
    • No additional parameters
  • fetchForums
    • forum_ids: Comma-separated list of forum IDs to fetch data for.
  • fetchTopics:
    • forum_ids: Comma-separated list of forum IDs to fetch topics from.
    • order_field: Field in the database to sort topics by (e.g. title, posts, last_post, etc.).
    • order_by: One of 'asc' or 'desc'; the direction to order topics by based on the supplied order_field.
    • offset: Integer offset to start pulling topics at. This is analagous to the first parameter of the LIMIT clause of an SQL query.
    • limit: Number of topics to retrieve. This is analagous to the second parameter of the LIMIT clause of an SQL query (or the only clause, if only one value is provided to LIMIT).
    • view_as_guest: Whether to retrieve results as a guest or not. This defaults to false, meaning topics are returned even if a guest (or anyone else) does not have access to view them.
 

Adding Functions

You can additionally add your own methods. For this article, we'll assume you're adding to the existing "ipb" module.

You first need to add a value to the $ALLOWED_METHODS array in interface/board/modules/ipb/methods.php specifying the method name and which parameters you expect to receive and what parameters you will respond to the request with. Then, add a method to the API_Server class in interface/board/modules/ipb/api.php. The method name will of course be the name of the method you're adding, and the parameters should be the parameters you listed as expecting in the $ALLOWED_METHODS array (in the same order they are listed in the configuration array).

Your method must call the __authenticate function (see any of the other methods for an example) and only send the reply if it returns true. This is for security purposes, to prevent any users from being able to make a request even if they are not authorized to.


Example

Here is a basic example showing how to make a request, and the expected response of the request. This example is copied from our XML-RPC library documentation.

PHP code to make the request:
 
<?php

define( 'IPS_XML_RPC_DEBUG_ON'  , 0 );
define( 'IPS_XML_RPC_DEBUG_FILE', '' );

// Adjust this path as needed
require_once( "ips_kernel/classXmlRpc.php" );

$classXmlRpc	= new classXmlRpc();

// Adjust the URL as needed, and supply a valid api_key
print_r($classXmlRpc->sendXmlRpc( "<url to your board>/interface/board/index.php", "helloBoard", array( 'api_module' => 'ipb', 'api_key' => '<api key>' ) ) );
exit;

You should get a print out similar to the following, showing that the communication (both sending it, and your board receiving, processing, and responding to it) was successful

 
Array
(
	[methodResponse] => Array
		(
			[params] => Array
				(
					[param] => Array
						(
							[value] => Array
								(
									[struct] => Array
										(
											[member] => Array
												(
													[0] => Array
														(
															[name] => board_name
															[value] => Array
																(
																	[string] => Invision Power Services
																)

														)
													[1] => Array
														(
															[name] => upload_url
															[value] => Array
																(
																	[string] => http://yourboardurl/uploads
																)
														)
													[2] => Array
														(
															[name] => ipb_img_url
															[value] => Array
																(
																	[string] =>
																)
														)
													[3] => Array
														(
															[name] => board_human_version
															[value] => Array
																(
																	[string] => 3.3.2
																)
														)
													[4] => Array
														(
															[name] => board_long_version
															[value] => Array
																(
																	[int] => 33013
																)
														)
												)
										)
								)
						)
				)
		)
)

 

Get more help

Customers with an active license can submit support requests to our knowledgeable techs via the client area

Client Area


Support forums

Ask other customers for advice on features, customization and running a community in our peer-to-peer support forums

Support forums