uapi documentation 2025 audit needed
Over the years I've gradually have gotten used to how the APIs work. Unfortunately the documentation really needs an update.
I have updated PHP over the years to not get "stuck" at any given version like so many others have. Almost every version has broken something in my platform's code which is fine, that is why I test on my local desktop before deploying to the live server.
As newer releases of PHP have debuted they have become increasingly stricter and I favor that. My platform uses the XML parser instead of the HTML parser because if there is an error I want to know. My competition is sloppy, I'm not.
So I realized I needed to use a new command, remove_autossl_excluded_domains (https://api.docs.cpanel.net/openapi/cpanel/operation/remove_autossl_excluded_domains/). Now I always use PHP functions such as isset() and count() for example. However the documentation about the JSON output if an error occurs suggests NULL. Yes, but what if there isn't an error? The metadata key returns an object. But what if there is an error? The documentation doesn't clarify that.
The problem is that I have to spend time figuring out how to determine if the command run via shell_exec() (e.g. $result = json_decode(shell_exec('uapi SSL remove_autossl_excluded_domains domains=\'www.domain.tld\' --output=json'), true);) was executed successfully or not. Is the error key set? Yes? There is no string? So I have to use strlen() but it's not a string, it's an array now. PHP throws errors for screwing this stuff up.
In short, I have to manually validate both the success and failure scenarios because the documentation doesn't set expectations. Without expectations we end up with assumptions and my assumption is that everything will break so I have to double the time required to validate each function that I implement.
I am asking that what we need to test for success and failure conditions be made explicit in the documentation. In example: isset($result['errors'] && count($result['errors']). Errors implies an array but the documentation does not. Essentially: is each key assigned an array or a string when applicable?
I would update the documentation to look something like the following:
"errors": null || array
"func" : string: 'set_autossl_excluded_domains'
Updating "errors" to null || array sets the expectations that if there are errors I need to use isset() and count(). If there is a string expectation I should use isset() and strlen() > 0.
Because the documentation is loose, again, I go out of my way to test intentionally successful and intentionally failed instances of executing the commands.
On my platform I rely on errors to be handled gracefully. If something doesn't work, fine. If a light bulb stops working it's not the same as getting a direct hit by an F5 tornado. But I can't implement graceful error handling if I'm always pressed for time and don't have proper documentation available.
So in short: knowing how to explicitly test for success and explicitly test for failure is my goal. Knowing if something will be null, an array and/or a string is very important. Knowing if something can sometimes be null or even if sometimes a string versus an array is also important. I know there is a lot of documentation though if the documentation audit I'm proposing were done it would make the documentation much easier to interpret, much quicker to test and make the experience implementing cPanel related code much more cooperative and desirable.
-
Hey hey! I spoke with the development team about this, and there are too many tests for us to possibly list every outcome. No matter what we documented on our side, there are various error states that would need to be accounted for, and we aren't planning on adjusting the docs at this time. Here's some potential states for just one call:
script they are executing via open exits nonzero which likely means non-json output (likely bug or cpsrvd downed)
script they are executing exits zero but does not return valid JSON (likely bug)
script they are executing exits zero, valid JSON but the metadata key does not exist at top level (shouldn't happen, likely a bug)
script they are executing exits zero, valid JSON, metadata key exists at top level, result key does not exist (likely bug)
script they are executing exits zero, valid JSON, metadata key exists at top level, result key exists beneath it but has values other than 0 or 1
script they are executing exits zero, valid JSON, metadata key exists at top level, result key exists beneath it and has value of 0
script they are executing exits zero, valid JSON, metadata key exists at top level, result key exists beneath it, has value of 1 BUT data key does not exist
script they are executing exits zero, valid JSON, metadata key exists at top level, result key exists beneath it, has value of 1, data key exists BUT doesn't have expected data structure type
script they are executing exits zero, valid JSON, metadata key exists at top level, result key exists beneath it, has value of 1, data key exists, has expected data structure type but none of the expected entries in resultant data structure.and there's just no way for us to include all of this, plus more, on each page.
0 -
Hi Rex, good to see you again!
So no, I think you've misinterpreted my request. I don't want to know every possibly error, hell no! I just want to know if errors if going to be a string '' and/or array [] and/or null. The same thing with the success checking. Does that make the request much more viable?
0 -
Oooooooh that makes more sense! I'm running this by some people now and I'll let you know what I find out!
1 -
Okay, apparently I missed it by that much since most of the people I want to poke about this have already run away for the weekend. I'll revisit this on Monday and see if I can get some answers from the development team then.
1 -
I just wanted to let you know I'm reaching out to the team about this today and I'll let you know what I find out!
1 -
The team does want to address this and validate the exit codes on the API, as that does seem like it would offer serious benefit. I'm looking into how I can make this happen, so I'll likely post another update.
1 -
Rex, thank you. I've been out all day running around so I'm just now seeing this. So could we please take an example API documentation page and do a before-and-after? That way there isn't any over-thinking or excess work done. Then once it's clear we're all on the same page of the same book in the same universe to then move forward on everything else with confidence? I should be more responsive this week than 8-9 hours lol...
0 -
Alright - I've spoken with both the dev team and the head of docs and everyone seems to be on board with the idea of making things better. The trick now is timing and resources - I wouldn't expect anything to happen with this for several weeks due to the holidays, wrapping up q4, and beginning q1. BUT, they all have a link to this case and I'll be sure to post updates once I get them.
If I get an advance copy of a before-and-after page I'll be sure to share that.
0 -
Rex, thank you very much! I completely comprehend, a lot of shifting going on as we head in to the heart of the holidays. This will end up speeding up development for other developers and myself when we need to implement,test and commit cPanel related code. Thank you!
0
Please sign in to leave a comment.
Comments
9 comments