Create backup through json-api?

[MACscr]

I prefer to work with JSON over XML whenever possible, so i created a nice little php function for accessing the json-api and its worked great. I used it to create a list of users for a reseller and also list their disk usage as well. Now I want to create a backup through the json api as well. Unfortunately I am not finding any documentation for doing that. Seems to only be available through the xml api. There is a restore option for json, just no creation. Am I missing something?

[MACscr]

Well, i think i figured part of it out. Here is my new url format:

https://hostname:2087/json-api/cpanel?cpanel_jsonapi_module=Fileman&cpanel_jsonapi_func=fullbackup&cpanel_jsonapi_apiversion=1&user=USERNAME&server=REMOTE_HOSTNAME&pass=#############&email=EMAILADDRESS&dest=passiveftp&port=21&rdir=backups%2F&

Unfortunately it seems backups cant be created with API2, so I am forced to use the format for API1. This is the response i get though and the backup never seems to happen:

object(stdClass)#56 (7) {
  ["apiversion"]=>
  string(1) "1"
  ["type"]=>
  string(5) "event"
  ["module"]=>
  string(7) "Fileman"
  ["func"]=>
  string(10) "fullbackup"
  ["source"]=>
  string(6) "module"
  ["data"]=>
  object(stdClass)#57 (1) {
    ["result"]=>
    string(0) ""
  }
  ["event"]=>
  object(stdClass)#58 (1) {
    ["result"]=>
    int(1)
  }
}

I cant seem to see where I could be going wrong though and there is obviously not an error being shown. I know I am authenticating correctly or else I wouldnt be getting that response at all and I can access the json-api with other functions, such as getting a user list based on the owner name. But that method uses API2 I think and is requires less variables. Im getting a bit desperate here. I would like to continue with a remote method and sticking with json.

[MACscr]

Ok, got it to work, seems you have to use arg-0, arg-1, etc, in place of the actual setting names (dest, rdir, etc). Seems a bit absurd, but at least its finally working now. Stinks the api didnt have the ability to tell me i was passing unusable vars.

[cPanelDavidN]

Hi MACscr,

You're correct, API1 arguments, when passed in a remote XML/JSON-API call, must have arg-0, arg-1, etc as the key names. This is a direct translation to the fact that API1 subroutines call take one or more parameters, in a prescribed order. API2, on the other hand, takes one parameter which is a Perl Hash (aka associative array for PHPers and the like).

From your output above, it looks like you're using PHP. Have you considered using our PHP XML-API client class or PHP PublicAPI client class [beta]? Our XML-API client class wouldn't have told you that the API1 arguments are order, but the new PublicAPI client class do have some rudimentary argument validation and would have complained. Still, it's not the same as having the server's parsing engine response with such an error message.

Regards,
-DavidN

[MACscr]

I want to be able to do it remotely and it appears the libraries are for doing local stuff. Plus JSON is not only easier to work with, its faster and even suggested in your docs. Plus having to use a library just adds unneeded bulk for my specific purpose IMHO.

[cPanelDavidN]

Hmmm...I think some clarification is in order:

I want to be able to do it remotely and it appears the libraries are for doing local stuff

Both client classes are specifically designed for remote calls. I'd be curious to know how you came to the opposite assumption?

The PublicAPI happens to have an optimization feature: it will auto-detection when it's being used on a cPanel system locally and will switch to a special socket based query mode with the cPanel daemon (which can cut down on the overhead of a network transmission and authentication for a process that's already auth'd and getting local data).

Plus JSON is not only easier to work with, its faster and even suggested in your docs.

Both client classes both support JSON (despite the name 'XML-API client class'). In the XML-API client class the method you'd want is "set_output('json')". The PublicAPI equivalent is a little more involved, at least, to explain. PublicAPI makes a distinction between setting the data response format and the PHP structure returned by the query method. So you can set your data response to be JSON (the default) or XML. The default PHP structure that is return is a special object ("Cpanel_Query_Object") which is an iterative object. This object has a method call 'getResponse()' which allows you to get the data formatted as an 'array', 'JSON' string, or 'XML' string. This allows for greater flexibility, especially if you know you want to mix JSON and XML data response formats due to quirks within the cPanel response engine, or more likely, you wish to mutate the response once it's been parsed. (PublicAPI has a SimpleXML parser/encoder and a DOMDocument parser/encoder so you can work around those quirks too. And actually, there's an interface for parsers, so technically anyone can write their own parser class and mutate with it instead of the array/JSON/XML that is shipped).

You are correct that JSON is typically faster on cPanel and Linux machines. However, in some tests, on some systems, the libxml (for XML parsing) can be nearly as fast as JSON and use significantly less RAM. But all my testing on cPanel systems has shown that JSON is the best all-around choice...shame I didn't have time (or editorial scope) to add my findings related to remote calls made from my Mac...as I've alluded above, it was interesting.

Subjectively, I think JSON can be a lot easier to work with too, albeit 'json_decode()' and 'json_encode()' aren't available prior to PHP 5.2. More importantly, when cPanel returns JSON data structures for API2 and XML-API calls, they should always be in list context if the function returns a list. However, because the cPanel XML is very, very simple, if you request XML return data structures and the returned data happens to only contain one result set, the PHP parsed expression with not be in list context. There's a hard-core thread about this here.

Plus having to use a library just adds unneeded bulk for my specific purpose IMHO.

The PublicAPI client class does require several other classes, those classes are collectively called the Cpanel PHP Library. I can complete understand how a developer would shy away from something like that. The Library was designed to be fairly barebones with enough ground covered to build a cPanel application (and have all the heavily lifting provided) as well as an extension library for a framework (for folks who already have a big, sophisticated application but just want the client to function like a driver to the cPanel server). So, it's flexibility and robustness come with the cost of being rather sprawling...especially if you have only a few specific remote api calls to accomplish. IIRC, the PublicAPI codebase is about 8k lines long (with PHP DocBlocks and comments) which is about 15 classes. That, of course, is not counting the Tests/ and Examples/ directories (which collectively add about 12.5k and another 20 classes to the package...all of which never get loaded unless you explicitly call them in your code).

On the other hand, the XML-API client class is just one class; it's a far cry from a library. It does come with a directory containing examples, another directory containing a PHPUnit test, and a changelog file. The class file is approximately 2170 lines long (including comments), of which, only about 400 or less are essential. These 'core' lines contain the accessor methods (getters/setters), the cURL/fopen wrapper methods, and the 3 query methods which structure the URL query according to the type of API call you wish to make ('api1_query()', 'api2_query()' and 'xmlapi_query()'...the latter will honor prior calls to 'set_output("json")' despite it's name).

Those are the facts and my opinion concerning JSON.

If you're project is better off not using a cPanel client classes, continues as you were.

Regards,
-DavidN

[NOTE: When I mention PublicAPI in this post, I'm referring specifically to the PHP client and not the Perl client. The functionality between the PHP and Perl versions are very similar, but the implementation (to which I speak of in this post) is different.]