Apis Networks  
Implementing SOAP
  - Implementing SOAP
  - SOAP Data Types
  - SOAP Authentication
  - Language Examples
- PHP4
- PHP5
- Perl
- Ruby
- Python
- Java
- VBScript
- JavaScript
  - SOAP Explorer
Introduction 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.
Introduction Understanding the Structure:
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:
Dashboard Metrics
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:
and if you're accessing it over SOAP, it transforms into
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 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.
Action Example
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:
and if we do it from the control panel directly, it's
Each programming language has its own special syntax (structure) of passing variables (e.g. "99077FD-76E03FDE-E29D9430-BFF2BF7B") and calling functions (e.g. auth_delete_soap_key), but before we dive into language-specific details, let's take a look at the basic data types SOAP handles and what each one is.

All Rights Reserved. Copyright © 2002-2008 Apis Networks, Inc. All trademarks are property of their legal owner.
Acceptable Use Policy | Terms of Service | Privacy Policy | Site Map | Domain Registration Agreement