HubBroker iPaaS - The HTTP protocol
HTTP (Hypertext Transfer Protocol) or HTTPS (HTTP secure) in combination with SSL/TLS is the preferred protocol to exchange XML business documents between trading partners and the HubBroker iPaaS. HTTP uses the client-server model: An HTTP client opens a TCP/IP socket connection and sends a request message to an HTTP server; the server then returns a response message. After delivering the response, the server closes the connection. The format of the request and response messages are similar. HubBroker iPaaS uses and supports the POST method to send/retrieve data to/from trading partners.
HTTP POST request
A POST request is used to send data to the server to be processed in some way, like by a CGI script, a webservice etc. The HTTP POST request contains a block of data sent in the message body and specific header lines:
- POST /invoke/inbound.soap:receiveSOAP HTTP/1.0 (path to the script, service, program processing the message; HTTP version)
- Content-Type: text/xml; charset=utf-8 (type of content and encoding of the message in the body)
- Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= ("username:password" credentials as base64 encoded string)
- Content-Length: (the length of the data stream in the body)
- Host: (server:port)
- (blank line)
- (the message to be sent)
HubBroker iPaaS Example HTTP POST request
The message in the body has to be well-formed XML wrapped into a SOAP envelope according to the HubBroker iPaaS SOAP envelope specification. HubBroker iPaaS is sending HTTP requests with SOAP messages and "Content-Type: text/xml; charset=utf-8" if no attachments are included. Inbound also "Content-Type: application/soap+xml; charset=utf-8" is accepted.
HTTP POST request with MIME
The request looks different if the content of the body is not pure XML but including other types of data, e.g. images, binary objects, as in case of attachments being added to the business document (order, invoice etc.). Then the Content-Type in the HTTP header has to be "multipart/related" and the body contains both SOAP envelope with XML payload (business document) and attachments in a MIME structure.
The maximum size of a message being accepted by HubBroker iPaaS is 7.5 MB.
HTTP response
Each message sent to HubBroker iPaaS via the HTTP protocol results in a synchronous response message back to the calling application. An HTTP response with a 2xx OK response code is returned if the message has successfully passed the inbound validation at HubBroker iPaaS (basic- and schema validation). When sending business documents to trading partners HubBroker iPaaS is considering a transaction as FINISHED when it receives the HTTP 2xx OK response code within 45 seconds (session timeout). Additionally, the SOAP-Response in the HTTP response body can hold warnings or information which helps for troubleshooting in case of errors but is not interpreted in case of success. The HTTP response consists of:
- HTTP/1.0 200 OK (HTTP version and a standard response code - 200, 400, 500 etc.)
- Content-Type: text/xml (a type of content of the response message in the body)
- Connection: Close (indicating that the HTTP connection is closed)
- Content-Length: (the length of the data stream in the body)
- (blank line)
- (the optional SOAP response message to be sent)
- HubBroker iPaaS Example HTTP POST response - message accepted
- HubBroker iPaaS Example HTTP POST response - message rejected due to XML schema validation
- The official list of valid HTTP response codes with explanations
The HTTP response body is SOAP-based and describes the result of the operation on a detailed level with the message id of the received document. If an error is detected (validation, duplicate check), the response message describes the reason for it. The content type of the HTTP response is always "text/xml". For duplicate messages, the response code can be modified per sender to e.g. "203" with a comprehensive error explanation in the SOAP response.
