|
|
|
 Introduction: |
"What is SOAP and how will it benefit me?"
SOAP is a method of sending and receiving data remotely between a server and client. SOAP is normally
transported over the HTTP transport where it is analyzed, executed, and corresponding information returned, back
to the client. SOAP libraries exist for every major programming language and performing a SOAP operation is nearly the same
easy operation in every language. That is what makes it so great.
As for the direct benefits of it, you can pull down any information directly from the server, perform any action on the server, or read any
data normally available from the server from the comfort of your own desktop, laptop, cell phone, PDA, you name it, it can happen.
For example, want to know how much bandwidth and disk space you're using? Before, it was an arduous process of loading up your
browser, recalling the link to the control panel, visting it, remembering your login, entering it all in,
and then finally pulling up the data from the dashboard. Now you can streamline the entire process by creating a widget in a desktop
monitoring application (e.g. Serious Samurize,
Konfabulator) that automatically updates that information
every 15 minutes from the comfort of your desktop.
We already have several examples up of how to accomplish those actions in various languages and through various applications.
What are you waiting for? The old Web interface to load up? Modernize your life by heading over to the examples.
Now that we have the foundation laid out, want to learn how to work with SOAP in esprit? You've come to the right place.
First thing first though is that you understand how esprit is designed and built. We'll start off by taking
a look at an example provision and explain the difference between what is directly embedded into the control panel
and what is deemed an external operation. External operations are not tightly integrated into the front-end of the control
panel (what you see when you login) and can thus be handled in nearly any form, SOAP being one of them.
|
|
|
| Understanding the Structure: |
 Metrics:
Metrics contain information about the state of your account. How many users you have on the account, when the domain will expire,
when the next billing date is, how much disk space you have used, et cetera. Most metrics are contained in the dashboard itself,
so we'll take a look at it to understand what the equivalent calls are:
Figure 1: Metrics in the Dashboard
Each number to the right corresponds to a SOAP operation embedded in the control panel. To the left, in the legend, the
functions and SOAP operations are listed. Functions are grouped into classes with the format of
<Class>::<Function> internally with the control panel. This is done to ensure two things,
first, we don't have duplicate functions in the control panel and secondly, to group similar functions inside a class.
In order to simplify the SOAP component, the format is very similar to the internal <Class>::<Function> format,
but with two changes: _Module is stripped from the class name and :: is replaced by _. Thus, for example,
if we want to determine the mail server name for our account, the call internally is:
Common_Module::get_mail_server_name common_get_mail_server_name
Note well: you will never access a function in apnscp esprit via the internal name. That's available solely from within
the control panel. You will always use the SOAP notation. Knowing the internal structure though is handy
for looking up the function information in the documentation.
Actions:
Actions differ from metrics in that instead of telling you something, they perform something for you. Retrieving the total bandwidth
used by your account is an action, but the value returned itself is a metric. Actions commonly occur within the sub-pages of the control panel,
or "provisions" as they are called. Let's check out the SOAP key generation page within the control panel to understand what all
goes on underneath.
Figure 2: Example Page of Actions
Every provision starts out with a generic template and is created on-the-fly with two items: static content defined specifically for the specific provision
(e.g. page help, title name of page, legends) and a snip of logic that controls what embedded functions to call in order to create the data that appears
on the page.
Static content is not accessible via SOAP; however, the dynamic function calls that the logic invokes is. Take for example the
"SOAP Keyring" provision above; the page title and help are both static content. They will appear exactly the same for every user
verbatim. Now for each identifier listed below, those are dynamic values retrieved via a single call to
Auth_Module::get_soap_keys.
Each of the identifiers
have a corresponding action — revoke. Upon clicking the trashcan icon, the identifier immediately to the right is deleted. Again this
is an action that takes a single parameter (also called "argument"), the identifier, to delete from the user's account. For example to delete the key 99077FD-76E03FDE-E29D9430-BFF2BF7B
from this account, we would call Auth_Module::delete_soap_key with the parameter "99077FD-76E03FDE-E29D9430-BFF2BF7B".
In SOAP, the function itself would look like:auth_delete_soap_key("99077FD-76E03FDE-E29D9430-BFF2BF7B");Auth_Module::delete_soap_key("99077FD-76E03FDE-E29D9430-BFF2BF7B")
|
|
Links:
