SOAP Services

From DreamFactory
Jump to: navigation, search

SOAP Services provide clients with REST-based access to XML-based SOAP remote services, taking much of the complexity out of the client access. DreamFactory takes care of converting the client request (JSON, etc.) to a SOAP request to the remote service, and the SOAP response to a easily consumed client response (JSON). DreamFactory takes the service's configured WSDL file and auto-generates a Live API service definition, determining available resources, required payloads, returned data types, and scriptable events.

Configuration

HTTP Services are managed via the api/v2/system/service API endpoint under the system service and have the service type of rws. The service type for information can be retrieved from here using the api/v2/system/service_type/rws endpoint.

Below is the format of a typical HTTP Service configuration. 

{
	"id": 7,
	"name": "example",
	"label": "Example SOAP Service",
	"description": "",
	"is_active": true,
	"type": "soap",
	"mutable": true,
	"deletable": true,
	"created_date": "2016-07-15 13:04:56",
	"last_modified_date": "2016-07-19 19:23:06",
	"created_by_id": "1",
	"last_modified_by_id": "1",
	"config": {
		"wsdl": "http://example.com/ExampleService.wsdl",
		"options": null,
		"headers": null,
		"cache_enabled": true,
		"cache_ttl": 0
	}
}

WSDL

For further info see, https://us3.php.net/manual/en/soapclient.soapclient.php
URI of the WSDL file or NULL if working in non-WSDL mode.

  • Note:

During development, WSDL caching may be disabled by the use of the soap.wsdl_cache_ttl php.ini setting otherwise changes made to the WSDL file will have no effect until soap.wsdl_cache_ttl is expired.

options:
An array of options. If working in WSDL mode, this parameter is optional. If working in non-WSDL mode, the location and URI options must be set, where location is the URL of the SOAP server to send the request to, and URI is the target namespace of the SOAP service.

The style and use options only work in non-WSDL mode. In WSDL mode, they come from the WSDL file.

The soap_version option should be one of either SOAP_1_1 or SOAP_1_2 to select SOAP 1.1 or 1.2, respectively. If omitted, 1.1 is used.

For HTTP authentication, the login and password options can be used to supply credentials. For making an HTTP connection through a proxy server, the options proxy_host, proxy_port, proxy_login and proxy_password are also available. For HTTPS client certificate authentication use local_cert and passphrase options. An authentication may be supplied in the authentication option. The authentication method may be either SOAP_AUTHENTICATION_BASIC (default) or SOAP_AUTHENTICATION_DIGEST.

The compression option allows to use compression of HTTP SOAP requests and responses.

The encoding option defines internal character encoding. This option does not change the encoding of SOAP requests (it is always utf-8), but converts strings into it.

The trace option enables tracing of request so faults can be backtraced. This defaults to FALSE

The classmap option can be used to map some WSDL types to PHP classes. This option must be an array with WSDL types as keys and names of PHP classes as values.

Setting the boolean trace option enables use of the methods SoapClient->__getLastRequest, SoapClient->__getLastRequestHeaders, SoapClient->__getLastResponse and SoapClient->__getLastResponseHeaders.

The exceptions option is a boolean value defining whether soap errors throw exceptions of type SoapFault.

The connection_timeout option defines a timeout in seconds for the connection to the SOAP service. This option does not define a timeout for services with slow responses. To limit the time to wait for calls to finish the default_socket_timeout setting is available.

The typemap option is an array of type mappings. Type mapping is an array with keys type_name, type_ns (namespace URI), from_xml (callback accepting one string parameter) and to_xml (callback accepting one object parameter).

The cache_wsdl option is one of WSDL_CACHE_NONE, WSDL_CACHE_DISK, WSDL_CACHE_MEMORY or WSDL_CACHE_BOTH.

The user_agent option specifies string to use in User-Agent header.

The stream_context option is a resource for context.

The features option is a bitmask of SOAP_SINGLE_ELEMENT_ARRAYS, SOAP_USE_XSI_ARRAY_TYPE, SOAP_WAIT_ONE_WAY_CALLS.

The keep_alive option is a boolean value defining whether to send the Connection: Keep-Alive header or Connection: close.

The ssl_method option is one of SOAP_SSL_METHOD_TLS, SOAP_SSL_METHOD_SSLv2, SOAP_SSL_METHOD_SSLv3 or SOAP_SSL_METHOD_SSLv23.

Examples

$client = new SoapClient("some.wsdl", array('login' = "some_name",
                                            'password'  = "some_password"));
 
 
$client = new SoapClient(null, array('location' = "http://localhost/soap.php",
                                     'uri' = "http://test-uri/"));


  • NTLM- If using NTLM username and password must be formatted as: 
"ntlm_username"
"ntlm_password"
  • If incorrect the exception will be thrown:
"Unable to register HTTP Handler"


SoapHeader::SoapHeader ( string $namespace , string $name [, mixed $data [, bool $mustunderstand = FALSE [, string $actor ]]] )
    • type - Picklist of generic or wsse.
    • namespace - String. Required. The namespace of the SOAP header element.
    • name - String. Required. The name of the SoapHeader object.
    • data - String. Optional. A SOAP header's content. It can be a scalar value or an object.
    • mustunderstand - Boolean. Defaults to false. Value of the mustUnderstand attribute of the SOAP header element.
    • actor - String. Optional. Value of the actor attribute of the SOAP header element.

Using SoapVar in Payloads

Sometimes the WSDL does not define every detail of a request payload, i.e. a request for multiple optional fields or objects. Starting with 2.5.1 (df-soap 0.8.1), this is supported by the use of the "soapvar" element. 

{
	"<field>": "<value>",
	"<field>": {
		"soapvar": {
			"type_name": "<object_name>",
			"type_namespace": "<object_namespace>",
			"encoding": "<encoding>",
			"node_name": "<outgoing_xml_node_name>",
			"node_namespace": "<outgoing_xml_node_namespace>",
			"data": {
				"<field>": "<value>",
				...
			}
		}
	}
}

Where the elements contained in the soapvar are as follows

  • data - Required. Array, String, Integer, etc. The data array or scalar value to pass as the SoapVar to be encoded as directed.
  • encoding - Optional. String or Integer. The encoding ID, one of the XSD_ constants (i.e. XSD_STRING) or SOAP_ENC_ARRAY for arrays or objects. If not provided, a determination is made based on the data given.
  • type_name - Required. String. The object type name of the SOAP element to use.
  • type_namespace - Optional. String. The object type namespace of the SOAP element to use.
  • node_name - Optional. String. The XML node name to use when adding a scalar the the outgoing payload.
  • node_namespace - Optional. String. The XML node namespace to use when adding a scalar the the outgoing payload.

Events

SOAP Services fire events based on the methods defined in the given WSDL file. For example, myservice.call_method.post would be generated for a call to POST http://example.com/api/v2/myservice/call_method.

Special Cases

WSSE Security

https://msdn.microsoft.com/en-us/library/ms977327.aspx?f=255&MSPPError=-2147217396#understw_topic4

The core thing is to define prefixes for namespaces and use them to fortify each and every tag. It's much better to use default types for fields whenever you can - so for password you have to list the type, for the Nonce it's already Base64.

Make sure that you check that the generated token is correct before you send it via XML and don't forget that the content of wsse:Password is Base64( SHA-1 (nonce + created + password) ) and date-time in wsu:Created can easily mess you up. Nonce can have different encodings so if you really want to force another encoding you'll have to look further into wsu namespace. 

<S11:Envelope xmlns:S11="..." xmlns:wsse="..." xmlns:wsu= "...">
  <S11:Header>
  ...
    <wsse:Security>
      <wsse:UsernameToken>
        <wsse:Username>NNK</wsse:Username>
        <wsse:Password Type="...#PasswordDigest">weYI3nXd8LjMNVksCKFV8t3rgHh3Rw==</wsse:Password>
        <wsse:Nonce>WScqanjCEAC4mQoBE07sAQ==</wsse:Nonce>
        <wsu:Created>2003-07-16T01:24:32</wsu:Created>
      </wsse:UsernameToken>
    </wsse:Security>
  ...
  </S11:Header>
...
</S11:Envelope>
Retrieved from "https://wiki.dreamfactory.com/index.php?title=DreamFactory/Features/SOAP_Services&oldid=34559"