API-docs updates : sites_web_domain_add

Discussion in 'Developers' Forum' started by TonyG, Oct 30, 2020.

  1. TonyG

    TonyG Active Member

    I've been working on a library of PHP functions that wrap the API, so that I can automate many manual operations. It would be nice to use an existing library if there is one somewhere, but if there isn't one published, I'm having fun and learning a lot while doing this, so it's all good. I'll publish my code at some point.

    Looking at the old sites_web_domain_add API doc page, there are many anomalies that I'd like to try to resolve, to update this doc page and others.

    In general, new parameters are not yet documented - that happens. To get all current fields, I used the sites_web_domain_get query and converted the response array into a template. That will then be used to send parameters in the Add query.

    It's generally documented that in the SOAP/REST queries we must send all fields to the server, not just a subset. But for an Add query, obvious fields should not be sent. For example, I don't believe we should send a document_root in a site creation query, because the site ID is generated when the site is created, and I believe the document root is generated as well. The system_group is the clientX ID, and since the client_id is provided in the call, I don't believe we should include this or the related sys_groupid field.

    So I'm opening this thread and hoping for some guidance about what is and is not required these days. I understand the API is a loose front-end to the core functions, without much validation. I could experiment with minimal settings and add more data until queries stop aborting for lack of information - but that's a bit sloppy, and it could leak-in invalid data that the UI might otherwise filter. I'd rather establish some guidelines here before I go further with this, about what should and should not go into the queries and the docs. I don't expect to resolve all of these anomalies here for the entire API. I'm just looking for a high-level guide so that I can continue with this and make corrections to the doc without having to ask about every function.

    And I'm sorry but while it might be required to look into the code for these functions, I'm kinda dreading that. I've been working on this stuff for a couple months and am now actually trying to use the system with real data. I need to write code to generate more data. Reading more code to figure out this system works will just put me more behind that I am already ... but I'll do what's required.

  2. Jesse Norell

    Jesse Norell Well-Known Member Staff Member Howtoforge Staff

    I've started something like that for an internal mail migration here, it only has mail related functions in it, and probably not all of them at that; I have in mind to publish it at some point, but right now it's still being worked on.

    This is more rambling and may or may not help, but I believe the api (and the interface, using same verification code?) uses the "tform.php" files to know what fields are available/required, set defaults, validate, etc. So for `sites_web_domain_add`, a quick grep finds the function defined in interface/lib/classes/remote.d/sites.inc.php, and a quick look at that finds it uses ../sites/form/web_vhost_domain.tform.php where eg. document_root has a NOTEMPTY validator and defaults to '', which... won't validate. :)

    So at this point I'd head to the user interface and create a website, and use the browser development tools to see what request is made. In this case it's a POST to /sites/web_vhost_domain_edit.php, so open up that file and search for document_root to see how it's constructed, and end up at line 1339.

    Some times trial & error is fairly quick, but there's probably no way around digging through the code for some of this.
  3. TonyG

    TonyG Active Member

    I hear ya - and I have been digging. Before I saw your note here I was going through the tform for mail user updates. It does seem that for now this is all just trial n error. Speaking of errors, there is an issue in the tform processing for a remote insert. So even if we get all of the fields right it won't work for now. Oh joy. :)
    Last edited: Nov 1, 2020
  4. TonyG

    TonyG Active Member

    Follow-up: I was wrong. That ticket that I posted is not a real bug. I updated the text with the accurate details. This all relates to updates to API docs. It's been a good exercise. I've learned a lot.
  5. Jesse Norell

    Jesse Norell Well-Known Member Staff Member Howtoforge Staff

    Finally reached that point: https://git.ispconfig.org/jnorell/RestAPI It is still just mail related functions, with some inconsistencies as an api, but it's usable.
    Richard Foley and TonyG like this.

Share This Page