How to call web services in Compiere
Compiere Web Service uses simple HTTP or HTTPS requests (GET or POST method) to support web services. The format of the request is very similar to Amazon Web Services, and contains references from Amazon documentation.
Query requests must contain an Actionparameter to indicate the action to be performed and a Signature parameter to indicate the "signature" of the the entire url. The response is an XML document that conforms to a schema.
Action must be the 1st parameter in a url and Signature must be the last parameter.
Method to generate signature
In org.compiere.gwt.ws.Util.java, we have this method to generate the signature.
Structure of a GET Request
The following is an example GET request that shows details for a Business Partner.
Because the GET requests are URLs, you must URL encode the parameter values. For example, in the preceding example request, the value for the MessageBody parameter is actually Your Message Text. However, spaces are not allowed in URLs, so each space is URL encoded as "%20". The rest of the example has not been URL encoded to make it easier for you to read.
Structure of a POST Request
SQS also accepts POST requests. With a POST request, you send the query parameters as a form in the HTTP request body as described in the following procedure.
To create a POST request
1. Assemble the query parameter names and values into a form.
This means you put the parameters and values together like you would for a GET request (with an ampersand separating each name-value pair). The following example shows a SendMessage request with the line breaks we use in this guide to make the information easier to read.
&MessageBody=Your Message Text
2. Form-URL-encode the form according to the Form Submission section of the HTML specification (for more information, go to http://www.w3.org/MarkUp/html-spec/html-spec_toc.html#SEC8.2.1).
3. Add the request signature to the form (for more information, see create signature.
4. Provide the resulting form as the body of the POST request.
5. Include the Content-Type HTTP header with the value set to application/x-www-form-urlencoded. The following example shows a sample POST Request in Compiere to create a Business Partner. The actual XML document containing data needs to be submitted along with the request.
Compiere Webservice requires no other HTTP headers in the request besides Content-Type. The authentication signature you provide is the same signature you would provide if you sent a GET request (for information about the signature, see create signature).
Create the Signature
1. Create the canonicalized query string that you need later in this procedure:
a. Sort the UTF-8 query string components by parameter name with natural byte ordering.
The parameters can come from the GET URI or from the POST body (when Content-Type is application/x-www-form-urlencoded).
b. URL encode the parameter name and values according to the following rules:
- Do not URL encode any of the unreserved characters that RFC 3986 defines.
These unreserved characters are A-Z, a-z, 0-9, hyphen ( - ), underscore ( _ ), period ( . ), and tilde ( ~ ).
- Percent encode all other characters with %XY, where X and Y are hex characters 0-9 and uppercase A-F.
- Percent encode extended UTF-8 characters in the form %XY%ZA....
- Percent encode the space character as %20 (and not +, as common encoding schemes do).
Currently all Compiere service parameter names use unreserved characters, so you don't need to encode them. However, you might want to include code to handle parameter names that use reserved characters, for possible future use.
c. Separate the encoded parameter names from their encoded values with the equals sign ( = ) (ASCII character 61), even if the parameter value is empty.d. Separate the name-value pairs with an ampersand ( & ) (ASCII code 38).
2. Create the string to sign according to the following pseudo-grammar (the "\n" represents an ASCII newline).
StringToSign = HTTPVerb + "\n" +
ValueOfHostHeaderInLowercase + "\n" +
HTTPRequestURI + "\n" +
CanonicalizedQueryString <from the preceding step>
The HTTPRequestURI component is the HTTP absolute path component of the URI up to, but not including, the query string. If the HTTPRequestURI is empty, use a forward slash ( / ).
3. Calculate an RFC 2104-compliant HMAC with the string you just created, your Secret Access Key as the key, and SHA1 as the hash algorithm.
For more information, go to http://www.rfc.net/rfc2104.html.
4. Convert the resulting value to base64.
5. Use the resulting value as the value of the Signature request parameter.
The following example shows how to call the Compiere Webservices using PHP. To run this PHP, you would need to get the following libraries: