We have had a flurry of integration tickets over the past week, which is awesome to see.\u00a0 Most of these tickets have come down to a couple of basic problems.\u00a0 The first of which is due to some confusion about how to utilize HTTP to call\u00a0 an API function.The second problem appears to stem from a lack of information API troubleshooting tools that come with cPanel\/WHM.<\/p>\n
The first of our common problems stem from some basic confusion about how to utilize HTTP to call our API functions.\u00a0 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.<\/p>\n
So, there are numerous things that need to be understood about using HTTP when working with our XML-API.\u00a0 The first point that needs to be made is that the GET HTTP call is limited to 2048 characters.\u00a0 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.\u00a0 This limit affects XML-API by limiting the number of characters that in can be passed via GET.\u00a0 If the number of characters exceeds 2048 (think of SSL certificates), the string will be truncated and the call will fail.\u00a0 This is why it is very important to always use POST with the XML API.<\/p>\n
The second issue that I\u2019ve been noticing is that people don\u2019t encode the data that they are passing to the XML-API.\u00a0 In most cases, this is fine; however, I\u2019ve had quite a few tickets where the developer\u00a0 is having issues with this.\u00a0 When passing something like an email account over HTTP via GET, it will have user@domain.com inside of the HTTP request.\u00a0 This is an issue because the @ symbol is reserved for specific uses, namely redirects or authentication.\u00a0 If you are using an HTTP client that does not automatically encode GET requests, the URL will be truncated.\u00a0 If you are using PHP for your interactions, the built-in url_encode function works really well for this.\u00a0 When developing in perl the URI::Escape module works quite well.<\/p>\n
When you run across issues with the XML-API, there are a few ways of troubleshooting them.\u00a0 The first is the most obvious:\u00a0 look at the error_log (located at \/usr\/local\/cpanel\/logs\/error_log).\u00a0 If there is an error with the call itself, it should show up in this log.\u00a0 Of course, this won\u2019t help much with errors inside of your application.\u00a0 For troubleshooting those, the easiest log to look at is the access_log at \/usr\/local\/cpanel\/logs\/access_log.\u00a0 This will show every URL called within cPanel using a format similar to Apache\u2019s \u2018combined\u2019 log style.<\/p>\n
A completely undocumented log that is really useful is the \u201clog-http-requests\u201d cpanel.config option.\u00a0 To enable this option:<\/p>\n
Open \/var\/cpanel\/cpanel.config in your preferred text editor. Another cool feature that we\u2019ve added in newer builds of cPanel 11.25 (build # 41121 and higher) is the ability to log POSTDATA sent to the server.\u00a0 To enable this simply add log-http-requests-postdata=1 to \/var\/cpanel\/cpanel.config and restart the service.\u00a0 This will add another line of output to the incoming_http_requests.log file displaying the POSTDATA passed to the server.<\/p>\n 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.\u00a0 This class does encoding, POST requests, and even provides some useful debugging information.<\/p>\n","protected":false},"excerpt":{"rendered":" We have had a flurry of integration tickets over the past week, which is awesome to see.\u00a0 Most of these tickets have come down to a couple of basic problems.\u00a0 The first of which is due to some confusion about how to utilize HTTP to call\u00a0 an API function.The second problem appears to stem from […]<\/p>\n","protected":false},"author":77,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"inline_featured_image":false,"footnotes":""},"categories":[49],"tags":[],"class_list":["post-60","post","type-post","status-publish","format-standard","hentry","category-products"],"acf":[],"yoast_head":"\n
\nAdd the following line to the file:
\nlog-http-requests=1
\nRestart cPanel:
\n\/etc\/init.d\/cpanel restart<\/em>
\nAfter doing this, if you run tail-f \/usr\/local\/cpanel\/logs\/incoming_http_requests.log<\/em> you will see something like
\n ]15421][10\/29\/2009:17:14:21 -0000][getreq 0]: [POST \/xml-api\/addip HTTP\/1.1
\n[15421][10\/29\/2009:17:14:21 -0000][headerparser 0]:Host: 127.0.0.1:2087
\n[15421][10\/29\/2009:17:14:21 -0000][headerparser 0]:Accept: *\/*
\n[15421][10\/29\/2009:17:14:21 -0000][headerparser 0]:Authorization: Basic *censored*
\n[15421][10\/29\/2009:17:14:21 -0000][headerparser 0]:Content-Type: application\/x-www-form-urlencoded
\n[15421][10\/29\/2009:17:14:21 -0000][headerparser 0]:Content-Length: 34
\n[15421][10\/29\/2009:17:14:21 -0000][killconnection]
\n[15421][10\/29\/2009:17:14:21 -0000][killconnection exit]<\/code>
\nThis allows you to ensure that the proper data is being sent to the server.<\/p>\n