Data & Services - Web Services
Configure SOAP web services for enterprise application integration
Overview
The Web Services section configures SOAP (Simple Object Access Protocol) web services in ColdFusion. While REST has become more popular for modern applications, SOAP web services remain important for enterprise integration and legacy system connectivity.
Creating SOAP Web Services
ColdFusion makes it easy to expose CFCs as SOAP web services with automatic WSDL generation.
CFC as Web Service
http://server/component.cfc?wsdlExample Web Service CFC
Basic web service exposing customer operations:
component displayname="Customer Service" hint="SOAP web service for customer operations" {
/**
* Get customer by ID
* @customerId Customer ID to retrieve
* @return Customer data structure
*/
remote struct function getCustomer(required numeric customerId)
returnformat="json"
access="remote"
hint="Retrieve customer information by ID" {
var customer = queryExecute(
"SELECT * FROM customers WHERE id = :id",
{ id: arguments.customerId }
);
if (customer.recordCount == 0) {
throw(type="CustomerNotFound", message="Customer not found");
}
return {
id: customer.id,
name: customer.name,
email: customer.email,
created: customer.created_date
};
}
/**
* Create new customer
* @name Customer name
* @email Customer email
* @return New customer ID
*/
remote numeric function createCustomer(
required string name,
required string email
) access="remote" hint="Create a new customer record" {
var result = queryExecute(
"INSERT INTO customers (name, email, created_date) VALUES (:name, :email, :created)",
{
name: arguments.name,
email: arguments.email,
created: now()
}
);
return result.generatedKey;
}
}<cfcomponent displayname="Customer Service" hint="SOAP web service for customer operations">
<!---
Get customer by ID
@customerId Customer ID to retrieve
@return Customer data structure
--->
<cffunction name="getCustomer" access="remote" returntype="struct"
returnformat="json" hint="Retrieve customer information by ID">
<cfargument name="customerId" type="numeric" required="true">
<cfquery name="customer">
SELECT * FROM customers
WHERE id = <cfqueryparam value="#arguments.customerId#" cfsqltype="cf_sql_integer">
</cfquery>
<cfif customer.recordCount EQ 0>
<cfthrow type="CustomerNotFound" message="Customer not found">
</cfif>
<cfreturn {
id: customer.id,
name: customer.name,
email: customer.email,
created: customer.created_date
}>
</cffunction>
<!---
Create new customer
@name Customer name
@email Customer email
@return New customer ID
--->
<cffunction name="createCustomer" access="remote" returntype="numeric"
hint="Create a new customer record">
<cfargument name="name" type="string" required="true">
<cfargument name="email" type="string" required="true">
<cfquery name="result" result="insertResult">
INSERT INTO customers (name, email, created_date)
VALUES (
<cfqueryparam value="#arguments.name#" cfsqltype="cf_sql_varchar">,
<cfqueryparam value="#arguments.email#" cfsqltype="cf_sql_varchar">,
<cfqueryparam value="#now()#" cfsqltype="cf_sql_timestamp">
)
</cfquery>
<cfreturn insertResult.generatedKey>
</cffunction>
</cfcomponent>- Documentation: Use hint attributes for WSDL documentation
- Type Safety: Always specify return types and argument types
- Error Handling: Use structured exceptions with meaningful messages
- Validation: Validate all inputs before processing
- Security: Implement authentication and authorization checks
Consuming SOAP Web Services
ColdFusion provides simple syntax for consuming external SOAP web services.
Example: Consuming a Web Service
Call external SOAP web service operations:
<cfscript>
// Create web service object
weatherService = createObject("webservice",
"http://api.weather.com/weatherService.cfc?wsdl"
);
// Call web service method
forecast = weatherService.getForecast(
zipCode = "90210",
days = 5
);
// Process results
writeOutput("Temperature: " & forecast.temperature);
writeOutput("Conditions: " & forecast.conditions);
</cfscript><!--- Create web service object --->
<cfinvoke
webservice="http://api.weather.com/weatherService.cfc?wsdl"
method="getForecast"
returnvariable="forecast">
<cfinvokeargument name="zipCode" value="90210">
<cfinvokeargument name="days" value="5">
</cfinvoke>
<!--- Process results --->
<cfoutput>
Temperature: #forecast.temperature#<br>
Conditions: #forecast.conditions#
</cfoutput>Web Service Caching
{cf-home}/stubs/Web Service Security
Secure your SOAP web services with authentication and WS-Security standards.
Basic Authentication
- Method
- HTTP Basic Auth with username/password
- Implementation
- Use addSOAPRequestHeader() or setHTTPBasicAuth()
- Security Level
- Low - requires HTTPS
Simple but must always use HTTPS to protect credentials in transit.
WS-Security
- Method
- SOAP message-level security with tokens
- Implementation
- Configure in Administrator or programmatically
- Security Level
- High - industry standard
Enterprise-grade security with encryption, signatures, and token-based authentication.
API Keys
- Method
- Custom SOAP headers with API keys
- Implementation
- Validate keys in CFC before processing
- Security Level
- Medium - simple but effective
Custom authentication using SOAP headers. Easy to implement for internal APIs.
Example: Basic Authentication
Secure web service calls with HTTP Basic Auth:
<cfscript>
// Create web service object
secureService = createObject("webservice",
"https://api.example.com/secureService.cfc?wsdl"
);
// Add authentication
secureService.setHTTPBasicAuth(
username = "apiuser",
password = "securepass123"
);
// Call authenticated method
result = secureService.getSecureData(
accountId = 12345
);
</cfscript><!--- Create web service object with authentication --->
<cfinvoke
webservice="https://api.example.com/secureService.cfc?wsdl"
method="getSecureData"
returnvariable="result"
username="apiuser"
password="securepass123">
<cfinvokeargument name="accountId" value="12345">
</cfinvoke>Best Practices
Use HTTPS Always
Always use HTTPS for web services in production to encrypt data in transit and protect credentials.
Implement Authentication
Require authentication for all non-public web services. Never expose sensitive operations without proper security.
Validate Inputs
Validate and sanitize all input parameters to prevent SQL injection and other security vulnerabilities.
Use WS-Security
Implement WS-Security for message-level security including encryption, signatures, and replay attack prevention.
Cache WSDL
Enable WSDL caching to avoid repeated parsing and improve performance. Clear cache when services are updated.
Monitor Performance
Monitor web service performance via Performance Monitoring Toolset (PMT) or APM tools to identify slow operations.
Document Services
Use hint attributes extensively to generate clear WSDL documentation for service consumers.
Error Handling
Return structured SOAP faults with meaningful error messages. Never expose internal implementation details.
Common Issues & Solutions
WSDL Not Updating
- Clear WSDL cache by deleting files from
{cf-home}/stubs/directory - Restart ColdFusion service to clear all caches
- Add
?wsdlquery parameter with timestamp to force refresh - Check CFC syntax for errors preventing compilation
Web Service Authentication Failing
- Verify credentials are correct and account is active
- Ensure using HTTPS (not HTTP) for authentication
- Check if WS-Security configuration matches server requirements
- Review web service logs for specific authentication errors
- Test with basic authentication first before implementing WS-Security
SOAP Fault Errors
- Check WSDL matches expected service contract
- Verify all required parameters are provided with correct types
- Review SOAP request/response in debugging tools
- Ensure data types in CFC match WSDL declarations
- Check for special characters in data that need escaping
- Validate XML structure against WSDL schema