What is the best way to document an XML-RPC API?

Question

I am using XML-RPC as the interface to my project's Java web service, and I need to document it. It's really more than simple documentation. It is intended to be a document that will explain why XML-RPC is being used, how to use it with different languages (we use Java, PHP, Javascript, Perl, C++, and Python), what all the methods do, what they return, and why they might cause a fault (exception). The reasons I am trying to explain every detail are (1) I won't be working on this project for much longer, and (2) some of the developers working on it have no experience with XML-RPC or similar protocols.

The goal of my question is to get suggestions about things I might be missing and how things should be structured. So far I have the following sections outlined:

• Why are we using XML-RPC?

  Explanation of why we chose XML-RPC over SOAP, etc.

• Example XML-RPC transactions

  Overall structure of an XML-RPC request/response/fault, with XML snippets. It will be similar to the Wikipedia XML-RPC article, but contained in the document for convenience.

• XML-RPC libraries

  Links to XML-RPC libraries for various languages we support, as well as examples of how to get up and running quickly.

• List of API methods

  A detailed description of each exposed method:

  • method name
  • list of parameters w/ descriptions
  • return type and description
  • situations in which a fault would be throw
  • descriptions of fault codes

All API methods are being documented using XML-RPC data types rather than a language-specific data type/interface like Boolean, List, Map, etc. Since the API is not too large, I am trying to create and share a Google doc with everything in it, so it can be read anywhere and edited by other developers when changes are made to the API.

Any thoughts or suggestions about this, or common mistakes made while documenting an API?

Answer 1

About telling the user of the technology: Tell the reader why exactly you chose the specific technology, what feature made it possible to come up with a solution for the problem you were trying to solve. What benefit does it have over other similar technologies.

Examples: Before this you need to document all the functions and arguments and their types your application is expecting. I'd suggest writing a Programmer's Guide for examples in conjunction with the API Reference document. This will also give you a chance to explain the order(if any) in which the API calls need to be passed.

Libraries: You are right about explaining the libraries, why they are needed and how to use/deploy them. A sort of an installation guide.

Do not think the reader is well read and that he knows about all the technologies you are using. I have had a bad experience in this regard, that I was required to write an API for a javascript library which connected to the server. I though I documented it well enough, but a simple thing as JSON was rocket science for the client, and we ended up writing a sample app for the client so that they could understand.

Answer 2

An important caveat about documenting API methods is that no matter how well you document them, prospective users are not going to read them carefully enough (or at all). Some people will avoid reading them and guess what they do based on the name, and some people will skim or read just the first sentence in it. As a result, by providing a full and accurate documentation you may actually be obfuscating the important details.

A really effective way to mitigate this problem is to take a lot of care to explicitly identify the "directives" among the "specifications". Generally, a directive is anything that could come as a surprise to the user who is only familiar with the method name and that the user can react to. For example, the fact that he should call another method, that there is a side effect, that there is a limitation, that there is an allocation responsibility. Anything else (like terms, what the method does, etc.) is not a directive, nor are trivial things (e.g., which parameters can be null).

If your documentation is HTML base, make sure to give the directives visually separate paragraphs, and to use something like bold or color to highlight them.

I can give you references on these problems, if you need; PM me. . I did my PhD on this and have a tool for Java (not XMLRPC) that offers additional solutions for this problem.

Answer 3

XML-RPC has a bit of a deficit when it comes to documenting the server's interface in a consistent way. XML-RPC really needs something like WSDL.

Each of the following are efforts made by the community to help fill this gap:

XML-RPC Introspection: http://xmlrpc-c.sourceforge.net/introspection.html

system.describeMethods: http://xmlrpc-epi.sourceforge.net/specs/rfc.system.describeMethods.php

system.getCapabilities: http://tech.groups.yahoo.com/group/xml-rpc/message/2897

XML-RPC fault codes: http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php

In my experience, it is best to provide concise documentation to your expected users, write your xml-rpc server to respond to an HTTP GET request with an HTML document that points users to the documentation, and at very least implement system.listMethods, system.methodHelp, and system.methodSignature. The first is necessary if you expect anyone to use the server. The second helps those users who will start by doing instead of reading documentation. The last is so your server behaves like those familiar with XML-RPC expect it to behave.

Answer 4

If you use python, use the docxmlrpcserver. It's self-documenting. POST goes to the service, GET goes to the documenter, and that returns html documentation.

see: http://revelworks.com/services/log/

Note that you can write whatever you like in the service description. You can write several paragraphs worth of stuff, detailing your strategy, reasons why, and best practices.