We have had a flurry of integration tickets over the past week, which is awesome to see. Most of these tickets have come down to a couple of basic problems. The first of which is due to some confusion about how to utilize HTTP to call an API function.The second problem appears to stem from a lack of information API troubleshooting tools that come with cPanel/WHM.
The first of our common problems stem from some basic confusion about how to utilize HTTP to call our API functions. The second of problem seems to come from a lack of information about how to use the tools that are available within cPanel and WHM for troubleshooting these API calls.
So, there are numerous things that need to be understood about using HTTP when working with our XML-API. The first point that needs to be made is that the GET HTTP call is limited to 2048 characters. The RFC itself does not specify any maximum size for a GET request; however, as this limitation has been imposed by browser manufacturers, HTTP servers and clients have implemented it as well. This limit affects XML-API by limiting the number of characters that in can be passed via GET. If the number of characters exceeds 2048 (think of SSL certificates), the string will be truncated and the call will fail. This is why it is very important to always use POST with the XML API.
The second issue that I’ve been noticing is that people don’t encode the data that they are passing to the XML-API. In most cases, this is fine; however, I’ve had quite a few tickets where the developer is having issues with this. When passing something like an email account over HTTP via GET, it will have user@domain.com inside of the HTTP request. This is an issue because the @ symbol is reserved for specific uses, namely redirects or authentication. If you are using an HTTP client that does not automatically encode GET requests, the URL will be truncated. If you are using PHP for your interactions, the built-in url_encode function works really well for this. When developing in perl the URI::Escape module works quite well.
When you run across issues with the XML-API, there are a few ways of troubleshooting them. The first is the most obvious: look at the error_log (located at /usr/local/cpanel/logs/error_log). If there is an error with the call itself, it should show up in this log. Of course, this won’t help much with errors inside of your application. For troubleshooting those, the easiest log to look at is the access_log at /usr/local/cpanel/logs/access_log. This will show every URL called within cPanel using a format similar to Apache’s ‘combined’ log style.
A completely undocumented log that is really useful is the “log-http-requests” cpanel.config option. To enable this option:
Open /var/cpanel/cpanel.config in your preferred text editor.
Add the following line to the file:
log-http-requests=1
Restart cPanel:
/etc/init.d/cpanel restart
After doing this, if you run tail-f /usr/local/cpanel/logs/incoming_http_requests.log you will see something like
]15421][10/29/2009:17:14:21 -0000][getreq 0]: [POST /xml-api/addip HTTP/1.1
[15421][10/29/2009:17:14:21 -0000][headerparser 0]:Host: 127.0.0.1:2087
[15421][10/29/2009:17:14:21 -0000][headerparser 0]:Accept: */*
[15421][10/29/2009:17:14:21 -0000][headerparser 0]:Authorization: Basic *censored*
[15421][10/29/2009:17:14:21 -0000][headerparser 0]:Content-Type: application/x-www-form-urlencoded
[15421][10/29/2009:17:14:21 -0000][headerparser 0]:Content-Length: 34
[15421][10/29/2009:17:14:21 -0000][killconnection]
[15421][10/29/2009:17:14:21 -0000][killconnection exit]
This allows you to ensure that the proper data is being sent to the server.
Another cool feature that we’ve added in newer builds of cPanel 11.25 (build # 41121 and higher) is the ability to log POSTDATA sent to the server. To enable this simply add log-http-requests-postdata=1 to /var/cpanel/cpanel.config and restart the service. This will add another line of output to the incoming_http_requests.log file displaying the POSTDATA passed to the server.
If you really run into a lot of trouble with the XML-API, I suggest using the XML-API PHP class or working with the API. This class does encoding, POST requests, and even provides some useful debugging information.
