+
Notes
+
+
These notes are new for v3.2 and the content will change.
+ This is currently in FAQ format, because the topics seem to be Frequently Asked Questions.
+ Over time, notes will also be added to individual function pages.
+ If you would like to help with this process, please visit the forum, and add your comments to this thread
+ which has been created for this purpose.
+ Thank you for your patience and collaboration.
+
+
+
What do we do to get started with API calls?
+
+
Create a "Remote" User in the ISPConfig UI. Check boxes there to assign permissions for
+ the kinds of queries that can be processed by that user.
+
Almost all API queries require a session_id. To get that, call the login function, sending the remote
+ username and password. The response will be a single value which will be used as your session ID for
+ a limited time period for all other requests.
+
Finishing with a logout request is recommended, but optional since the session IDs expire.
+
+
+
How do I get all records with a _get request?
+
Rather than using a single integer ID as a primary key selector (domain_id, group_id,
+ etc), use -1. Where the primary key for a _get request is a string, use an empty array ' [] '. Do not
+ use an empty string ' "" ', which is itself a valid string and will/should return an empty array result.
+
+
+
Are defaults used if we only send some of the defined parameters?
+
No, there are no default values except where explicitly noted. For example, in the
+ system_config_get function, the key element is optional because it is documented as defaulting to an
+ empty string. For all requests, except where documented otherwise, send all documented parameters.
+
+
Examples are provided for SOAP, why not for REST?
+
The REST API supports all functions and can be exactly substituted for SOAP examples.
+ For all functions, the request and response parameters are the same for SOAP and REST.
+
+
Are there examples for cURL? Python? C#? JavaScript? (anything else...)
+
The documentation details request and response parameters which can be passed using any
+ language or toolchain. The URL always includes the function name. Queries are always sent via POST. The
+ result is always in the same JSON format. Use Postman or another tool to generate code in your preferred
+ languages.
+
+
I created a new record (domain, mail user, etc). Why isn't it showing in the UI?
+
If a parent ID is invalid, a transaction may be accepted, with a record created under a
+ different parent entity.
+
+
+
Why does a response show a successful result when there is no data?
+
Carefully check the names and values being sent. Invalid name/value pairs are ignored. A
+ request that does not include a valid request paramenter is requesting nothing, so the return value is
+ nothing. The query was successful, and returned no data.
+
+
Why are parameters $session_id and others being ignored?
+
The documentation shows PHP function syntax. SOAP and REST parameters do not include the
+ leading $dollar-sign
+
+
Key Concept:
+
Based on the above you may be thinking there is very little error checking with this
+ API. That is correct. As noted by Jesse Norell:
"The api is largely just an interface to the
+ database tables, and will usually accept what you send, whether that's consistent/correct or not. It
+ can be a feature, eg. you can create a mail alias first before creating the mailbox to which it
+ forwards, but it does mean you have a lot more testing to do on your side because you can't just
+ rely on an error to be thrown if you send inconsistent data."
+
+
+
What is sys_userid and sys_groupid?
+
+
These fields are referenced often in the developer forum and in code, usually with some confusion.
+ These internal database fields are used in SQL queries to determine parent/child client
+ relationships. The fields are not passed to API calls, with the exception of one function,
+ client_get_id which is a convenience function to return the client_id for a sys_userid. In the past
+ other functions included these keys in the request. Now, when a function request includes a
+ client_id, at query time a lookup is done to get the internal sys_userid for that client.
+
The sys_userid can identify the creator of a record. This may be the ID of the local/UI user or the
+ remote/API user that is logging in to create records. If a client record is created without a
+ reseller, both the sys_userid and the sys_groupid are the same user ID.
+
If a client record is created with a reseller, the meaning of the fields is completely different. The
+ sys_userid is not a logged-in user ID. It is a new ID that represents the client under the reseller.
+ The sys_groupid for a client under a reseller is (a foreign-key to) the sys_userid of the client
+ record for the reseller. In this scenario, the sys_groupid establishes a child-to-parent
+ relationship.
+
+
+
What domains are the 'domains_' functions operating on?
+
The 'domains_' functions update the 'domains' table, which is used by the domain limit
+ module. Clients and resellers are restricted to the domains in this table. To activate domain limits, go
+ to System > Interface > Main Config, then to the Domains tab. Logout/in. Then go to Sites, Add or Edit a
+ site, the "Domain" dropdown list uses this table.
+
+
What will be here next?
+
Maybe something you write...
+
+