Invoking LMPI

Authentication

To successfully invoke the LMP API, several requirements should be fulfilled. The following is an example of customized HTTP headers that you should specify for every request made to the API:

HTTP header sample:

x-access-token: {Put your access token here}
x-posix-time: 1363797148
x-signature: rnBCnS6YWHvR5PnkM2J44IobfTGcQL039xkRbosIMe8=
x-traceid: 95b794e7-7f4b-4f20-95b6-a16d4143199e
content-type: application/json; charset=utf-8

Please pay attention to header elements as some of them are compulsory headers required for LMPI API to respond to your request. Following table explains it in detail:

x-signature Generation

The x-signature proves that the message is composed by a trusted Business Partner who owns the Secret Key. It also prevents the message from been hijacked or resent by other parties when sent via the Internet, even when all transactions are forced to be sent over SSL. The x-signature header should be composed using the following matrix.

Payload = [x-posix-time] + [http method] + [request_uri] + [body content]

x-signature = HMAC-SHA256(secret_key, UTF-8 Encoding(Payload))

Payload

Following table explains elements that composes into the Payload string:

x-signature

Once the Payload is generated, it is ready to be hashed using the Secret Key that was provided to generate the signature. The following algorithm explains how the signature is generated.

Base64 ( HMAC-SHA256(secret_key, Payload) )

The first step is to generate a HMAC-SHA256 hash of the Payload using your Secret Key, and then convert the binary into Base64 string.

As for this design, you need to generate a unique x-signature in every request, resulting in a different signature for each request. The x-signature will be verified by the API server in every request.

Request Content

Apart from the header elements. The HTTP request body should also include a valid JSON data structure of the data that you need to send to the LMPI API, if required. The details of the body content is included in each API Specification.

Following the above request to invoke a Create Customer API, if the request was invoked successfully you should have received a response body similar to the following example:

{
    company_id : "17363415-4A9F-4A01-8153-10B8F35B50B1",
    user :
    {
        id : "3CB3C2A5-94C5-4D57-9B97-CF4FCC47FF77",
        login_name : "staygreen_greenery",
        password : "93oap1jv0z"
    }
}

C# Sample Code

Generating x-posix-time

// Verify that if a PosixTime is 15 minutes before or after the server time.
// serverTime: Current server time.
// posixStr: A posix string of seconds.
// timeRangeinMinutes: You may specify a time range in minute. Default value is 15 minutes.
// returns: True if the posixStr time is within +-15 minutes range of the given server time.

public static bool VerifyPosixTime(string posixStr, int timeRangeinMinutes = 15)
{
    long posixSeconds;
    if (!Int64.TryParse(posixStr, out posixSeconds)) return false;

    var from = DateTimeToPosixTimestamp(DateTime.UtcNow.AddMinutes(-timeRangeinMinutes));
    var to = DateTimeToPosixTimestamp(DateTime.UtcNow.AddMinutes(timeRangeinMinutes));

    return (posixSeconds >= from) && (posixSeconds <= to);
}

// Methods to convert DateTime to Posix time(seconds) in Unix time stamp.
// dateTime: Unix time stamp to convert.
// returns: Return Unix time stamp as long type.

public static long DateTimeToPosixTimestamp(DateTime dateTime)
{
    TimeSpan unixTimeSpan = (dateTime - new DateTime(1970, 1, 1, 0, 0, 0));
    return (long) unixTimeSpan.TotalSeconds;
}

Generating x-signature

// Generate a x-signature header value that's required to invoke LMPI API interface.
// secret: The secret key used to hash.
// unixTimestamp: Number of seconds after 1970-01-01 til now.
// method: HTTP method used to invoke LMPI.
// requestUri: The request URI without server host. The request URI should be encoded.
// content: HTTP request content in binary. Pass in null if no content is to be sent to server.
// hexstring: A hexstring of HMAC-SHA256 hashed value will be assigned to this parameter.
// returns: Base64 string encoded x-signature.

public static string GenerateSignature(string secret, long unixTimestamp, string method, string requestUri, byte[] content, out string hexstring)
{
    var posix = unixTimestamp.ToString();
    var payload = posix + method.ToUpper() + requestUri +
        ((content == null) ? "" : CalculateMD5Hash(content));

    HMAC hash = new HMACSHA256();
    hash.Initialize();
    hash.Key = Encoding.UTF8.GetBytes(secret);

    var byteArr = hash.ComputeHash(Encoding.UTF8.GetBytes(payload));
    hexstring = ByteArrayToHexString(byteArr);

    return Convert.ToBase64String(byteArr);
}

// Calculates MD5 Hash of a binary and return it as a BASE64 string.
// input: Binary to be calculated.
// returns: MD5 hashed string result in BASE64.

public static string CalculateMD5Hash(byte[] input)
{
    // step 1, calculate MD5 hash from input
    MD5 md5 = MD5.Create();
    byte[] hash = md5.ComputeHash(input);

    return Convert.ToBase64String(hash);
}

// Converts a byte array into HexString.
// ba: Byte array to be converted.
// returns: HEX String.

public static string ByteArrayToHexString(byte[] ba)
{
    var sb = new StringBuilder(ba.Length*2);
    foreach (var b in ba)
    {
        sb.AppendFormat("{0:x2}", b);
    }
    return sb.ToString();
}