This topic describes the communication protocol between APIs and the webservice Followzup, to be used as a reference in the development of new APIs.
Whatever language is used, it must have the AES and RSA encryption libraries compatible with PHP, used in the development of the webservice, witch handles the requests of the information channels. Current APIs can be used as a reference.
In order for the API to be available for download from the Followzup website, it must complies with the standard APIs already in place:
#idchannel# ... Literal to be replaced by Channel-ID; #pubkey64# .... Literal to be replaced with RSA public key (base64 format); #pubkeymod# ... Literal to be replaced with RSA public key (module component) #pubkeypux# ... Literal to be replaced with RSA public key (index component)
All communication between the API and the webservice is performed through POST. For information channels requests, the POST destination URL is “http:
The API should define the following POST variables:
|id||Contains the identification of the requester, with no encryption (Channel-ID);|
|key||Contains the temporary AES key encrypted with the public key and encoded in Base64;|
|frame||Contains the XML request, encrypted with the temporary AES key and encoded in Base64.|
In response to the POST, the webservice returns the XML POST response, which should not mistaken with the XML request response, as described below. The POST response XML includes 3 tags:
<?xml version="1.0" encoding="utf-8"?> <followzup> <retcode>return-code</retcode> <retframe>xml-request-response</retframe> <retmd5>md5-hash</retmd5> </followzup>
The XML request sent to the webservice contains the parameters needed to execute the command. This XML is built by the API from the parameters provided by the application.
In addition to the command to be executed and the parameters required for its execution, the XML request must include the request sequence, which corresponds to an integer starting from 1 at channel creation or RSA key renewal. After a request with sequence N, the next request must have the sequence N + 1.
IMPORTANT: The request sequence number included in this XML should not to be mistaken with the sequence number provided by the application to the API, since it corresponds to the last sequence used. The sequence number provided by the application must be added in 1 before being inserted into the XL request. If the application does not provide the last sequence used (optional parameter), the API must fetch the last sequence in the instantiated object and add 1.
XML request response format (invalid sequence):
<?xml version="1.0" encoding="utf-8"?> <followzup> <seq>Last-sequence</seq> </followzup>
When it finishes its execution, the API returns a array of 3 elements to the application, they are:
With the exception of return code 6101, handled by the API, other errors codes are returned to the application.