Skip to content

Commit 122066d

Browse files
author
CaptainStarbuck
committed
First commit of Notes/FAQs to content.html
1 parent 5e5a945 commit 122066d

File tree

1 file changed

+158
-43
lines changed

1 file changed

+158
-43
lines changed

‎remoting_client/API-docs/content.html‎

Lines changed: 158 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,159 @@
11
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2-
<html><head>
3-
<title>ISPCOnfig 3 remote API documentation</title>
4-
5-
6-
7-
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
8-
9-
10-
<style type="text/css">
11-
<!--
12-
.command {
13-
padding: 1em;
14-
border: 1px dashed #2f6fab;
15-
color: black;
16-
background-color: #f9f9f9;
17-
line-height: 1.1em;
18-
font-family: Courier New, Courier, mono;
19-
font-size: 12px;
20-
font-style: italic;
21-
}
22-
23-
.system {
24-
color: black;
25-
font-family: Courier New, Courier, mono;
26-
font-size: 12px;
27-
font-style: italic;
28-
}
29-
30-
.highlight {
31-
color: #FF0000;
32-
font-family: Georgia, "Times New Roman", Times, serif;
33-
font-size: 12px;
34-
text-decoration: underline;
35-
}
36-
-->
37-
</style></head><body style="color: rgb(0, 0, 0); background-color:#FFFFFF;;" alink="#804080" link="#804080" vlink="#603060">
38-
<div style="padding:40px">
39-
<h2>Home</h2>
40-
<br>
41-
ISPConfig 3 remote API documentation.
42-
</div>
43-
44-
</body></html>
2+
<html>
3+
4+
<head>
5+
<title>ISPCOnfig 3 remote API documentation</title>
6+
7+
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
8+
9+
<style type="text/css">
10+
<!--
11+
.command {
12+
padding: 1em;
13+
border: 1px dashed #2f6fab;
14+
color: black;
15+
background-color: #f9f9f9;
16+
line-height: 1.1em;
17+
font-family: Courier New, Courier, mono;
18+
font-size: 12px;
19+
font-style: italic;
20+
}
21+
22+
.notes {
23+
color: #17075c;
24+
font-family: Georgia, "Times New Roman", Times, serif;
25+
font-size: 14px;
26+
27+
}
28+
29+
.preface {
30+
color: black;
31+
font-family: Georgia, "Times New Roman", Times, serif;
32+
font-size: 14px;
33+
}
34+
35+
a:link,
36+
a:visited {
37+
text-decoration: none;
38+
}
39+
40+
41+
a:hover,
42+
a:active {
43+
text-decoration: underline;
44+
}
45+
46+
.question {
47+
font-size: 14px;
48+
padding: 0em 0em 0em 1em;
49+
}
50+
51+
.answer {
52+
padding: 0em 0em 0em 2em;
53+
}
54+
-->
55+
</style>
56+
</head>
57+
58+
<body>
59+
<div style="padding:40px">
60+
<h2>ISPConfig 3 Remote API Documentation</h2>
61+
<div class="notes">
62+
<h3>Notes</h3>
63+
64+
<p class="preface">These notes are new for v3.2 and the content will change.<br />
65+
This is currently in FAQ format, because the topics seem to be Frequently Asked Questions.<br />
66+
Over time, notes will also be added to individual function pages.<br />
67+
If you would like to help with this process, please visit the forum, and add your comments to <a
68+
href="https://www.howtoforge.com/community/threads/api-doc-you-can-help.84944/">this thread</a>
69+
which has been created for this purpose.<br />
70+
Thank you for your patience and collaboration.
71+
</p>
72+
73+
<h4 class="question">What do we do to get started with API calls?</h4>
74+
<div class="answer">
75+
<p>Create a "Remote" User in the ISPConfig UI. Check boxes there to assign permissions for
76+
the kinds of queries that can be processed by that user.</p>
77+
<p>Almost all API queries require a session_id. To get that, call the login function, sending the remote
78+
username and password. The response will be a single value which will be used as your session ID for
79+
a limited time period for all other requests.</p>
80+
<p>Finishing with a logout request is recommended, but optional since the session IDs expire.</p>
81+
</div>
82+
83+
<h4 class="question">How do I get all records with a _get request?</h4>
84+
<div class="answer">Rather than using a single integer ID as a primary key selector (domain_id, group_id,
85+
etc), use -1. Where the primary key for a _get request is a string, use an empty array ' [] '. Do not
86+
use an empty string ' "" ', which is itself a valid string and will/should return an empty array result.
87+
</div>
88+
89+
<h4 class="question">Are defaults used if we only send some of the defined parameters?</h4>
90+
<div class="answer">No, there are no default values except where explicitly noted. For example, in the
91+
system_config_get function, the key element is optional because it is documented as defaulting to an
92+
empty string. For all requests, except where documented otherwise, send all documented parameters.</div>
93+
94+
<h4 class="question">Examples are provided for SOAP, why not for REST?</h4>
95+
<div class="answer">The REST API supports all functions and can be exactly substituted for SOAP examples.
96+
For all functions, the request and response parameters are the same for SOAP and REST.</div>
97+
98+
<h4 class="question">Are there examples for cURL? Python? C#? JavaScript? (anything else...)</h4>
99+
<div class="answer">The documentation details request and response parameters which can be passed using any
100+
language or toolchain. The URL always includes the function name. Queries are always sent via POST. The
101+
result is always in the same JSON format. Use Postman or another tool to generate code in your preferred
102+
languages.</div>
103+
104+
<h4 class="question">I created a new record (domain, mail user, etc). Why isn't it showing in the UI?</h4>
105+
<div class="answer">If a parent ID is invalid, a transaction may be accepted, with a record created under a
106+
different parent entity.
107+
</div>
108+
109+
<h4 class="question">Why does a response show a successful result when there is no data?</h4>
110+
<div class="answer">Carefully check the names and values being sent. Invalid name/value pairs are ignored. A
111+
request that does not include a valid request paramenter is requesting nothing, so the return value is
112+
nothing. The query was successful, and returned no data.</div>
113+
114+
<h4 class="question">Why are parameters $session_id and others being ignored?</h4>
115+
<div class="answer">The documentation shows PHP function syntax. SOAP and REST parameters do not include the
116+
leading $dollar-sign</div>
117+
118+
<h4 class="question">Key Concept:</h4>
119+
<div class="answer">Based on the above you may be thinking there is very little error checking with this
120+
API. That is correct. As noted by Jesse Norell: <blockquote>"The api is largely just an interface to the
121+
database tables, and will usually accept what you send, whether that's consistent/correct or not. It
122+
can be a feature, eg. you can create a mail alias first before creating the mailbox to which it
123+
forwards, but it does mean you have a lot more testing to do on your side because you can't just
124+
rely on an error to be thrown if you send inconsistent data."</blockquote>
125+
</div>
126+
127+
<h4 class="question">What is sys_userid and sys_groupid?</h4>
128+
<div class="answer">
129+
<p>These fields are referenced often in the developer forum and in code, usually with some confusion.
130+
These internal database fields are used in SQL queries to determine parent/child client
131+
relationships. The fields are not passed to API calls, with the exception of one function,
132+
client_get_id which is a convenience function to return the client_id for a sys_userid. In the past
133+
other functions included these keys in the request. Now, when a function request includes a
134+
client_id, at query time a lookup is done to get the internal sys_userid for that client.</p>
135+
<p>The sys_userid can identify the creator of a record. This may be the ID of the local/UI user or the
136+
remote/API user that is logging in to create records. If a client record is created without a
137+
reseller, both the sys_userid and the sys_groupid are the same user ID.</p>
138+
<p>If a client record is created with a reseller, the meaning of the fields is completely different. The
139+
sys_userid is not a logged-in user ID. It is a new ID that represents the client under the reseller.
140+
The sys_groupid for a client under a reseller is (a foreign-key to) the sys_userid of the client
141+
record for the reseller. In this scenario, the sys_groupid establishes a child-to-parent
142+
relationship.</p>
143+
</div>
144+
145+
<h4 class="question">What domains are the 'domains_' functions operating on?</h4>
146+
<div class="answer">The 'domains_' functions update the 'domains' table, which is used by the domain limit
147+
module. Clients and resellers are restricted to the domains in this table. To activate domain limits, go
148+
to System > Interface > Main Config, then to the Domains tab. Logout/in. Then go to Sites, Add or Edit a
149+
site, the "Domain" dropdown list uses this table.</div>
150+
151+
<h4 class="question">What will be here next?</h4>
152+
<div class="answer">Maybe something you write... </div>
153+
154+
</div>
155+
</div>
156+
157+
</body>
158+
159+
</html>

0 commit comments

Comments
 (0)