Remote operations on Drupal objects. Technical details.

In the previous article Drupal with Android integration: make posts and upload photos. i wrote the introduction about to integrate Drupal with Android. In this article i'll explain the communication technical details. If you need some guidlines, about how xml-rpc is implemented in Drupal or you need the information about the remote methods it exposes, this article will be useful for you. If you need to develop an app, that will create, edit or delete pages, files, comments, etc. This article will give you information about how to make it.

Xml-rpc background.
Xml-rpc is a lightweight remote procedure calls protocol. It's not require methods description as, for example, with SOAP. Xml-rpc server exposes a set of remote methods, with input arguments and return value types. It support the following data types:

• int integer value
• double double-precision floating point value
• boolean boolean value
• string string value
• dateTime date/time value
• base64 base64 encoded binary data
• array array of values
• struct structure, where each member has name and value (similar to associative arrays)

int, double, boolean, string, dateTime and base64 are primitive types. array and struct are complex types, consisting of other values.

Examples:
struct node.create(struct node)
Method takes one input argument as structure, and returns structure value.

struct user.login(string, string)
Method takes two string input arguments, and returns structure value.

Drupal exposes a set of methods through xml-rpc.
Drupal xml-rpc servers are implemented in modules, in hook_xmlrpc (or by defining service resources, but this method is not in scope of this article). There are built-in methods, and you can create your own.

Most of the operations on Drupal objects, that are accessible through xml-rpc, are CRUD (create-read-update-delete). For example, for node operations are: node.create, node.retrieve, node.update, node.delete, node.index. The same is for applied for the most Drupal objects: comments, users, files, taxonomy terms. Only replace node with appropriate object type in method name. Most of the objects are identified by it's integer id: nid (node identifier), cid (comment identifier), fid (file identifier), and so on. retrieve, update and delete methods takes object id as first argument.

Authorization.
Authorization must be performed before calling the methods, that require an authorized user. Most of the methods, described in this article, must be called by an authorized user.

struct user.login(string username, string password)
Method to perform user login. It takes username and password arguments, and returns structure containing session params (sessid and session_name) and nested structure with information about user (email, uid, etc).
If you need to perform remote actions that require authorization, you must call this method first. You need to store sessid and session_name returned values, as they are identify openned user session. This values will be sent as cookie for all subsequent remote calls.

user.logout()
Perform logout. This method must be called, when to more actions will be performed, to close Drupal session.

Users operations.
User information is passed in structure with the following members:

• name - user name
• mail  - email address
• pass - plain text unencrypted password

These properties can be passed, but are optional:

• status - 0 for blocked, otherwise will be active by default
• notify - 1 to notify user of new account, will not notify by default

Roles can be passed in a roles property, which is an associative array formatted with '' => '', not including the authenticated user role, which is given by default.

This structure is passed to create, register and update methods as input argument.
Users are identified by integer value - uid (user identifier).

struct user.create(struct account)
Create the new user, specified by account structure. This method may be called only by authorized users with 'administer users' permission.

struct user.retrieve(int uid)
Retrieves a user account information. User is specified by uid (user identifier). Returned structure contains user account information.

struct user.update(int uid, struct account)
Update the existing user, specified by uid (user identifier). New user's data is specified by accout input argument. Calling user must have 'administer users' permission.

boolean user.delete(int uid)
Removes the user, specified by uid. Returns true, if user is successfully deleted, false - overwise.

array user.index(int page, string fields, array parameters, int pagesize)
Get list of users. All arguments are optional. This method can split result to pages. page argument specifies the page number to return, fields - what fields to be returned, parameters - is the parameters used to build SQL WHERE clause, pagesize - specifies size of the page. Returned value is an array of structures with requested users. If method is called without arguments, it will return all users.
For example: you have 100 users, setting pagesize = 20 and page = 2, will return users 40-60.

struct user.register(struct account)

Register a new user. This method may be called by only unauthorized user (no user.login call before it). User's data is passed in account argument. The difference between register and create methods, is that register is called by an anonymous user, while create can by called only by user with 'administer users' permission.

Node operations.
Node operations are CRUD (create-read-update-delete). Node is identified by nid (node identifier), and node information is passed and returned in structure with the following members:

• type - node type (page, story, etc)
• title - node title
• body - node body
• nid - node identifier (returned by retrieve, create, update methods)

struct node.create(struct node)
Creates a new node. It takes structure containing information about node to create. Method returns structure with created node information. Input and output structure differs in that, output is assigned nid (node identifier).

struct node.retrieve(string nid)
Retrieves the node content. Input argument is nid (node identifier). Returned value is structure with node information.

struct node.update(string nid, struct node)
Updates an existing node. Input arguments are nid and structure with node information (node type, nid, title, body, etc). Method returns structure with updated node information.

boolean node.delete(string nid)
Remove the node, specified by nid (node identifier). Returns true, if node successfully deleted, false - overwise.

array node.index(int page, string fields, array parameters, int pagesize)
Get list of nodes. All arguments are optional. This method can split result to pages. page argument specifies the page number to return, fields - what fields to be returned, parameters - is the parameters used to build SQL WHERE clause, pagesize - specifies size of the page. Returned value is an array of structures with requested nodes. If method is called without arguments, it will return all nodes.

For example: you have 100 nodes, setting pagesize = 20 and page = 2, will return nodes 40-60.

array node.files(int nid, int file_contents)
This method returns files associated with a node. Node is specified by nid (node identifier). file_contents argument specifies, whether or not to return file contents. Returned value is an array of structures with file information (see File manipulation section for details, about file structures).

array node.comments(int nid, int count, int offset)
Get node comments. Node specified by nid argument. count specifies comments count to return, offset specifies index of the first comment to return. Method returns an array of structures with comments information (see Comments operations section for details, about comment structure). To call this method comment module must be enabled.

Comments operations.
Comment operations are use the same CRUD approach, as other objects. Comment information is passed in structure with the following members:

• author - name of the author of comment
• date - date of the comment. Value 'now' 
• subject - the subject of the comment
• comment_body
• nid - node identifier
• pid - parent comment id
• format - comment format

struct comment.create(struct comment)
Create a new comment. Comment data specified by by comment argument. Method returns created comment information.

struct comment.retrieve(int cid)
Returns the comment, specified by cid (comment identifier). Method returns struct with comment information.

struct comment.update(int cid, struct comment)
Update an existing comment. Comment specified by cid argument, new comment data by comment argument. Method returns updated comment information.

boolean comment.delete(int cid)
Delete the comment, specified by cid (comment identifier). Returns true if comment is successfully removed, false - overwise.

array comment.index(int page, string fields, array parameters, int pagesize)

Get list of comments. All arguments are optional. This method can split result to pages. page argument specifies the page number to return, fields - what fields to be returned, parameters - is the parameters used to build SQL WHERE clause, pagesize - specifies size of the page. Returned value is an array of structures with requested comments. If method is called without arguments, it will return all comments.

For example: you have 100 comments, setting pagesize = 20 and page = 2, will return comments 40-60.

int comment.countAll(int nid)
Method returns the number of comments for the given node. Node is specified by nid (node identifier).

int comment.countNew(int nid, int since)
Method returns the number of new comments on a given node since a given timestamp. nid argument specifies the node, since specifies timestamp since that to return comments.

File operations.
File operations use the same CRUD approach, as other objects. Files identified by integer fids (file identifiers), and file described by the structure with the following members:

• filename - file name
• filepath - file path
• file - file data encoded as base64

struct file.create(struct file)
Create a new file. file input argument is structure, describing file. Method returns structure with created file information. Input and output structure differs in that, output has assigned fid (file identifier).

struct file.retrieve(int fid, int file_contents)
Retrieve the file, specified by fid (file identifier). file_contents argument specifies, whether or not to return file content. Structure returned by method, contains file description.

boolean file.delete(int fid)
Remove the file, specified by fid (file identifier). Returns true if file is successfully deleted, false - overwise.

array file.index(int page, string fields, array parameters, int pagesize)

Get list of files. All arguments are optional. This method can split result to pages. page argument specifies the page number to return, fields - what fields to be returned, parameters - is the parameters used to build SQL WHERE clause, pagesize - specifies size of the page. Returned value is an array of structures with requested files. If method is called without arguments, it will return all files.

For example: you have 100 files, setting pagesize = 20 and page = 2, will return files 40-60.

System calls.

System calls are intended to get server capabilities, list of method it exposes, method signatures, gettting, setting and deleting system varibles.

array system.methodSignature(string method)
Returns requested method signature. Method is specified by method argument, which is method name. Returned value is an array of strings, which are names of types of method arguments.

struct system.getCapabilities()
Returns server capabilities, as members of struct. Member names are names of capabilities. Member values are structures with specUrl and specVersion members. Example of capabilities are: xmlrpc, system.multicall, introspection, json-rpc.

array system.listMethods()
Enumerates the methods implemented by xml-rpc server. Method not takes input arguments. It returns an array of strings, each of which is the name of a method implemented by server.

string system.methodHelp(string method)
Returns method's help string. Method name is specified by method argument, which is the string with requested method name.

struct system.connect()
Returns the details of current logged in user and session (sessid and session_name). The returned structure is the same as with user.login method.

string system.get_variable(string name, string default)
Returns the value of a system variable using variable_get().

system.set_variable(string name, string value)
Sets the value of a system variable using variable_set().

system.del_variable(string name)

Deletes a system variable using variable_del().

Summary.
I described, the principles of xml-rpc,  how it works with Drupal and what actions can be performed with Drupal using remote methods. There are also blog, taxonomy and other methods, but they are not in scope of this article. Also, there are other remote procedure protocols, supported by services module.

Please, send me your comments and suggestions.

Links.
Xml-rpc specification: http://xmlrpc.scripting.com/spec.html
Drupal services module: http://drupal.org/project/services