Page tree
Skip to end of metadata
Go to start of metadata

For instructions on how to find the relevant endpoint for the SOAP API, see Introduction to Jade APIs.

Introduction

The Jade User API and Jade Admin API SOAP 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 the response are packaged as XML messages that have a header and a body.

For the Jade APIs, all API messages are sent via HTTPS requests. The XML for the SOAP request is sent as an HTTP POST request with a special SOAPAction header; the response is sent back as the response to the POST. All Jade User API and Admin API calls are encrypted with SSL (that is, as HTTPS) to protect the privacy of your data. 

The header describes metadata about the message. The body of the message specifies the requested operation (such as createCustomer) along with any applicable parameters (such as the parameters for the new customer).

The requests that a web service can process are 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. It also includes definitions of the SOAP header elements and the faults thrown in the case of an error.

Toolkits

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

The toolkits help generate stubs that know how to locate the Jade Admin API service. You would typically generate stubs for each service using the toolkit and then write your client application against the stubs.

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. Commonly used toolkits include:

  • Java: JAX-WS
  • Perl: SOAP::Lite
  • PHP: SoapClient
  • Python: ZSI

Note that the Jade APIs uses document/literal style. Some toolkits work differently for rpc-style web services than for document-style.

If you are using Java, we also supply a client library. This obviates the need for you to use a separate toolkit.

To learn more about SOAP, see the SOAP Tutorial at http://www.w3schools.com/.

Namespaces

All operations and complex types defined in the Jade Admin API web services are associated with the following XML namespace:

Where cp.example.com is the domain name associated with the endpoint.

Lowercase types shown throughout this guide (for fields, parameters, and return types) are XMLSchema datatypes and are associated with the following namespace:

  • No labels