In order to properly make any request to Flowroute API v1, you must generate the HMAC-SHA1 hexdigest (RFC 2104) on a message string. At a high level, the computation can be expressed as follows:
signature = hex(hmac_sha1(API_secret_key, message_string)
The message string is composed of certain details of the API request. It is formatted as a sequence of tokens separated by newline characters (\n). The sequence is shown in the following table:
|The date and time, to the second, of the message. This must be the same timestamp, precise to the second, used in the X-Timestamp header.|
| HTTP Method
GET, PUT, POST, or PATCH.
|The type of action applied to the message. This must be the same HTTP method used in the header.|
| MD5 Body Hash
|The message-digest algorithm (MD5). This must always be computed for the PUT, POST, and PATCH HTTP methods. If the body is empty for these methods then the MD5 should be computed on an empty string. For GET methods this token must be blank.|
| Canonical Request URI
|See Canonical Request-URI below for instructions on preparing the request.|
The concatenated example of the message_string from above, using the PUT HTTP method should resemble:
2015-09-05T21:29:22Z\n PUT\n ea63c300c845f3e76d8f5827aa0a1f89\n https://api.flowroute.com/v1/example/14045551212\n
You must ensure that you add a UTC timestamp in theX-Timestampheader of the HTTP request. This will help to prevent a replay attack, a type of network attack. The value must be the current timestamp in the UTC timezone, precise to the second and formatted according to ISO 8601:X-Timestamp: 2015-09-05T21:29:22Z
This timestamp in the X-Timestamp header must be the same exact timestamp used in generate the signature.
The Canonical Request-URI is a string that represents the request in a stable way. Two requests with the same meaning, i.e., reordered query parameters, are represented by the same Canonical Request-URI. It is constructed as follows:
canonical_ruri = url_scheme + "://" + net_location + path + "\n" + ordered_query_params xx", "111"], ["msg", "hello,world"]]
Theordered_query_paramsnames and values should be encoded as they would be in the URL; i.e., they should use URL-plus encoding. For example, a space should be replaced with a plus [+].
|Request URI Field||Example||Description|
|url_scheme||https||The secure protocol to use. HTTPS is always used for the live API.|
|net_location||api.flowroute.com||The requested domain.|
|path||/available-tns/tns/||URI to the requested resource. For example, /available-tns/tns|
|"\n"||\n||Inserts an escape sequence, or a new line.|
|ordered_query_params||[["nxx", "222"], ["npa", "111"], ["nxx", "111"], ["msg", "hello,world"]]||GET query parameters, ordered first by name and then by value.|
In the following example, if URI field values are as follows,
- url_scheme = https
- net_location = api.flowroute.com
- path = /available-tns/tns/
- query_parameters = [["nxx", "222"], ["npa", "111"], ["nxx", "111"], ["msg", "hello,world"]]
then the Canonical Request-URI after assembling the tokens and ordering and encoding the query parameters would be:
Use UTF-8 character encoding for the query parameters before URL-encoding them.