Based on the feedback we’ve received from developers working with the API, the SOAP protocol (Simple Object Access Protocol) did prove to add a great deal of friction when trying to programmatically post a simple request to the API. Every post needed to be wrapped in a SOAP Envelope, not only did this add extra payload to the request and response stream it was also very unforgiving if the envelope did not precisely confirm to the spec.
You can now dispense with the SOAP envelope and just HTTP POST the xml (in the message body) directly to this URL. Here is a VB.NET example on how this can be coded in your application, examples in other languages will be posted shortly.
Dim req As HttpWebRequest = WebRequest.Create("https://quickfile.co.uk/WebServices/API/invoices.ashx")
req.Method = "POST"
req.ContentType = "application/xml;charset=UTF-8"
req.KeepAlive = False
req.Accept = "application/xml;charset=UTF-8"
Dim writer As New StreamWriter(req.GetRequestStream())
writer.WriteLine("<Invoice_Get>....</Invoice_Get>") '<<<<<< INSERT YOUR XML HERE
writer.Close()
Dim rsp As WebResponse
rsp = req.GetResponse()
Dim sr As New StreamReader(rsp.GetResponseStream)
Dim xmlStringResponse as string = sr.ReadToEnd
C# Example
HttpWebRequest req = WebRequest.Create("https://quickfile.co.uk/WebServices/API/invoices.ashx");
req.Method = "POST";
req.ContentType = "application/xml;charset=UTF-8";
req.KeepAlive = false;
req.Accept = "application/xml;charset=UTF-8";
StreamWriter writer = new StreamWriter(req.GetRequestStream());
writer.WriteLine("<Invoice_Get>....</Invoice_Get>"); //<<<<<< INSERT YOUR XML HERE
writer.Close();
WebResponse rsp = default(WebResponse);
rsp = req.GetResponse();
StreamReader sr = new StreamReader(rsp.GetResponseStream);
string xmlStringResponse = sr.ReadToEnd;
Note: This is omitting the ‘https’ protocol, and using the ‘http’ protocol. While trying to use HTTPS, I ran into an error, and had to add this line to the cURL:
Increase in verbosity and complexity for the client.
Potentially unnecessary overhead in simpler use cases.
My question is …
Why add a “payload” wrapper around the Header and Body in the API request
In RESTful APIs, this extra nesting is less common, as REST prioritizes simplicity.
In SOAP APIs, which are highly structured, a wrapper equivalent to payload (like <Envelope>) is standard.
Why Include a “Payload” Wrapper?
Encapsulation for Consistency:
The payload acts as a single container for all the message content. This can make it easier for the server to parse the request, especially if the API uses a standardized format for all message types.
Encapsulation ensures that additional top-level properties (e.g., metadata, versioning) can be added outside the payload without interfering with the structure of the core data.
Versioning and Extensibility:
Wrapping Header and Body under payload provides flexibility for future versions. If the API evolves, the developer could add properties outside payload (e.g., timestamp, signature) without affecting the structure inside it.
Standardization Across Different APIs:
Some APIs are designed with uniform data structures, especially when multiple endpoints or services are involved. Wrapping Header and Body in payload ensures that all requests follow a similar structure, simplifying implementation across different teams or systems.
Compatibility with Middleware:
Middleware systems or gateways that process API requests might expect a consistent top-level key (like payload) for easier parsing and routing.
Is This Common?
This practice isn’t uncommon but depends on the API design philosophy. Some systems prioritize:
Minimalism: Avoid unnecessary nesting for simplicity and clarity.
Structure and Standardization: Use wrappers like payload to support extensibility and uniformity.
For instance:
In RESTful APIs, this extra nesting is less common, as REST prioritizes simplicity.
In SOAP APIs, which are highly structured, a wrapper equivalent to payload (like <Envelope>) is standard.
Is It Necessary?
From a purely functional perspective, you’re correct:
The Header and Body together already constitute the “payload.”
Adding the payload wrapper introduces an additional nesting level that may seem redundant and increases verbosity.
However, the decision often comes down to design preferences or specific requirements of the API ecosystem.
Trade-offs:
Pros:
Adds structure and flexibility for future changes.
Consistent schema for parsing and validation tools.
Easier integration with middleware or multi-service platforms.
Cons:
Increases verbosity and complexity for the client.
Potentially unnecessary overhead in simpler use cases.
Conclusion:
While it’s not strictly necessary, using a payload wrapper can reflect a deliberate design choice for extensibility and uniformity. Whether it’s “unnecessary” depends on the specific goals and standards of the API.
So it’s less of a question that needs a fix but more about getting an idea of the general design philosophy chosen.