Getting started with SOAP API

About SOAP

The Form.com API Web Services use document-style versions of the simple object access protocol (SOAP). A client program sends a SOAP request; the web service processes the request and sends a response. Both the request and response are packaged as XML messages that have a header and a body. 

For the Form.com API, all API messages are sent via HTTPS requests. THe XML for the SOAP request is sent as an HTTPS POST request with a special SOAP action header; the response is sent back as the response to the POST. If you use HTTPS requests, all Form.com API calls are encrypted with SSL( that is, as HTTPS) to protect the privacy of your data.

The header describes metadata about the message. In the case of the Form.com API Web-services, the header must include the username and password for logging into the Form.com account. The body of the message specifies the requested operation (such as getAccount) along with any applicable parameters (such as the data for the id of requested account). 

The request that a web service can process is defined in a web-services definition language (WSDL) file in XML. The WSDL file describes the operations that the web-service can perform, the required parameters for each operation, and the response for each operation.

MSOAP toolkits

Typically, to use the Form.com API Web Services you should download a toolkit that knows how to interpret WSDL files and how to encode and decode XML request and response messages. When Form.com API Web Service receives a request, it sends back a response as an XML message. The web service toolkits know how to parse the response and return data structure or object back to the caller, as appropriate for a language.

The exact toolkit you would use depends on the language you are using. Some toolkits do more for you or work better than others. Some take care of all the XML for you; others require you to write some XML yourself. The commonly used toolkits include:

• Java

• Windows

Form.com API uses document/literal style SOAP, not rpc/encoded style. Some toolkits work differently for document-style web services than for rpc-style. If you use a SOAP toolkit, you should rarely have to write XML code to use the Form.com API Web services, since the toolkits handle the XML generation. Some toolkits, however, may require you to hand-code some of the XML yourself.

Getting started in Java

Java provides a specification for working with web-services called JAX-WS. Reference implementation libraries are available for download here:

https://jax-ws.java.net/

JAX-WS provides a very useful tool, called wsimport, to generate Java code based on the WSDL web service definition. To generate Java code with wsimport you will need to provide a link to the WSDL web service definition that would you like to use.

The tool will generate packages starting with com.keysurvey.api.v73. For instance, for the FormDesingManagementService the following classes will be generated:

import com.keysurvey.api.v73.form.design.FormDesignManagement;
import com.keysurvey.api.v73.form.design.FormDesignManagementService;

WorldAPP platform web services are only available to the authenticated users, so you will need to provide a username and password to an instance of the service that is used. The following code snippet illustrates how to call a service providing the authentication parameters to it:

import
com.keysurvey.api.v73.form.design.FormDesignManagement;
import com.keysurvey.api.v73.form.design.FormDesignManagementService;
public class WorldAPPApiHelper {
  private FormDesignManagementService formDesignManagementService;
  private String m_username = "user";
    private String m_password = "password";
    public FormDesignManagementService getFormDesignManagementService() {
        if (formDesignManagementService != null) {
            return formDesignManagementService;
        } else {
            FormDesignManagement service = new FormDesignManagement();
            formDesignManagementService =
service.getFormDesignManagementServicePort();
            ((BindingProvider)
formDesignManagementService).getRequestContext().put(BindingProvider.USERNAME_PROPERTY,
 m_username);
            ((BindingProvider)
formDesignManagementService).getRequestContext().put(BindingProvider.PASSWORD_PROPERTY,
 m_password);
            return formDesignManagementService;
        }
    }
}

So whenever you would need an access to the FormDesignManagementService you would be able to obtain access to it using the getFormDesignManagementService() method.Other services could be accessed in a similar way.

Many modern Java IDEs, such as Eclipse, IntelliJ IDEA and NetBeans provide built-in tool or plugins to generate the Java code from the WSDL definitions using dialog-based user interface, so there may be no need to.

Getting started in C#.NET

Microsoft .NET framework also provides methods for accessing generating native .NET code based on the WSDL web service definitions. Visual Studio provides a graphical interface to generate native code. To generate code from web service definition you will need to add a Web reference. Here are step-by-step instructions:

1. In Visual Studio, right click on references of your project and select Add Web-reference.

2. Cut and paste the URL to the WSDL (see the list of links here) into the URL field and click Go.

3. Once the web service has been found, change the Web reference name to your convenience, for instance to com.keysurvey.api.v73 and click Add reference.

From this point, you should be able to use the web service.

Providing authentication parameters to the web service could be done in the following way:

using System.Net;
using System.Web.Services.Protocols;
using com.worldapp.api.v73.LaunchManagementService;
...
  private static LaunchManagement GetLaunchManagementService(string userName, string password)
  {
    LaunchManagement LaunchManagement = new LaunchManagement();
    LaunchManagement.Credentials = new NetworkCredential(userName, password);
    return LaunchManagement;
  }
...

Getting started in other languages

Using the SOAP-based web services in other languages and platforms is also fairly straightforward. Popular SOAP libraries for other languages include but are not limited to the following: 

1. PHP provides a Soap framework with documentation available here: http://php.net/manual/en/book.soap.php

2. Python: there are a number of tools to use SOAP web services in python, one of the most popular being SUDS: https://fedorahosted.org/suds/

3. Ruby on Rails has a built-in soap/wsdlDriver.

4. Perl: there is a library available to implement SOAP in Perl.

It is important to specify a correct domain name when putting a link to the WSDL service definition to generate code in order to authenticate properly.

Make sure that you use the same domain name (such as http://app.keysurvey.com, http://app.form.com  or a custom domain name for branded accounts) that you use to log into the web interface.