User Tools

Site Tools


en-120-api-dev


Developing new APIs

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.



API Structure

In order for the API to be available for download from the Followzup website, it must complies with the standard APIs already in place:

  • The API source name should be fzup.EXT, where EXT corresponds to the file extension according to the language used.
  • The source code should contain the literals shown in the table below, which will be identified and replaced by Followzup when the API is downloaded. These literals correspond to the constants that identify the attributes of each channel. They are:
      #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)
  • The API should implements a class, which will be instantiated by the application and should contain the methods constructor, decrypt and submit.
  • The methods must receive parameters from the applications into an array of strings, where each element of the array will have a parameter name and its value, separated by the equal sign (“=”).
  • The instantiated object must maintains (once instantiated), the last sequence number used in the last request to the webservice, and supplies the sequence number of the new requests in case of the applications does not provide the sequence parameter.
  • The decrypt method should return a string.
  • The submit method should return an array of strings and handles the return code 6101 (sequence error).



Webservice communication

All communication between the API and the webservice is performed through POST. For information channels requests, the POST destination URL is “http://followzup.com/wschannel”.

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.



XML POST response

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>

where:

  • retcode: Return code of the requested command represented by 4 numeric digits or “0” (zero) for successfully execution;
  • retframe: Contains the XML request response, encrypted with the temporary key AES and encoded in Base64. The XML request response depends on the command that was requested and the AES key used in its encryption is the same were used when the request was sent;
  • retmd5: Contains the MD5 hash of the retframe tag, to be validated by the requester.



Request sequence number

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>

Where:

  • Last-sequence: Sequence number used in the last request.



The API response to the application

When it finishes its execution, the API returns a array of 3 elements to the application, they are:

  • array[0]: Contains the return code of the request;

  • array[1]: Contains the sequence number used in the request;

  • array[2]: Contains the XML request response (decrypted and decoded).

With the exception of return code 6101, handled by the API, other errors codes are returned to the application.



Available Commands

Here are the available commands for sending requests from information channels:

  • SMSG: Send messages;
  • CHCK: Check users.


en-120-api-dev.txt · Last modified: 2017/05/30 07:14 by admin

Page Tools