Download Response
The following is an example of a JSON download response from the RouteLink® that includes 3 events in a JSON array. The first and last are add events where one includes the optional CPR.
{
"events":[
{
"action":"add",
"crn":"8005001212",
"ror":"ROR01",
"sha1":"<40 chars>",
"cpr":null,
"id" : 1000
},
{
"action":"delete",
"crn":"8006001212",
"id" : 1001
},
{
"action":"add",
"crn":"8007001212",
"ror":"AR26",
"sha1":"<40 chars>",
"cpr":"<variable length base64 encoded CPR>"
"id" : 1002
}
]
}
Field Descriptions
| Field | Range | Comments |
| events | an ordered array | A list that MUST be processed in order to maintain the accuracy of the client's local DB. |
| action | "add", "delete", "cpr" or "audit request" | Add or delete a CRN from the client DB. A redundant add (for an already active CRN) must be treated as a replace of the CRN’s data, such as replacing the ROR (and the CPR, if present). |
| crn | exactly 10 printable digits | Usually, a 10 char CRN (e.g. "8005551212"). But for template CPRs, this value can start with the number "0". |
| ror | 1 to 5 printable chars | The Responsible Organization (Resp Org) ID associated with the CRN. This is always present for an "add" and never present for a "delete". |
| sha1 | exactly 40 printable hex digits | The SHA-1 hash of the associated binary CPR (not the base64 version). A SHA-1 hash is exactly 40 characters long, as printable hex. For example: "E076B32E287452057362532D38E239F9462D3AF4".The field is always present for an "add" and never present for a "delete". |
| cpr | characters | The Call Processing Record (CPR) exactly as defined in the "798" specification. However, since the CPR contains binary (non-printable) data, the CPR is translated using base64 conversion into printable data. When the client receives the base64 printable version, it converts it back to the original binary version. Once converted back to binary, the CPR (in binary form) has a variable length up to a maximum of 170,000 bytes. This field is only present for an "add" and even then it is optional and only sent the first time the CPR sha-1 hash is encountered. The client is required to save this value. The next time the same sha-1 hash occurs, null is sent, and the client should refer to the earlier CPR value. The sha-1 hash is always against the binary version, not the base64 (printable) version. |
| id |
Number
It may also be set to null (see description). |
This value represents an index used by RouteLink to track various data types. It is provided to an API client to allow it to request specific messages that may have been missed. An API client should provide the last (highest) id value it received from RouteLink as the last Index field on the next request to RouteLink.
This value may be null when RouteLink is performing an audit with an API client or while requesting cpr. |
Download Responses with No Events
If the RouteLink Server has no events to send in the response, or if the RouteLink Server is currently unable to reply with events for any reason, then an empty event list is sent. The RouteLink Client must assume that there is no more data to currently download, and try again later.
Please Note: The client must pause 60 seconds before a retry before attempting to download again.
The JSON for an empty event array is:
{"events" : [] } // the empty event array
CRN “add”, SHA-1, and the Optional CPR
When an add is encountered, the entire JSON Call Processing Record (CPR) is hashed using the SHA-1 algorithm. The algorithm produces a 20-byte hexadecimal value that is converted into 40 printable bytes and sent in the "sha1" parameter of the "add" event.
When a unique SHA-1 hash is encountered for the first time by the RouteLink Server, it sends the full CPR as well as its SHA-1 hash to the RouteLink Client. The CPR is sent as base64 (printable) but the SHA-1 hash is performed on the binary form of the CPR. An example of base64 translation is demonstrated here in a UNIX environment:
$ echo -n "example cpr data" | base64
ZXhhbXBsZSBjcHIgZGF0YQ== // the value sent in JSON
And here is an example base64 decode:
$ echo -n "ZXhhbXBsZSBjcHIgZGF0YQ==" | base64 --decode
example cpr data // the original (binary) data
The RouteLink Client MUST keep track of both the SHA-1 hash and the CPR in its local DB for later audits. Also, when the RouteLink Server encounters the same SHA-1 hash in future "add" events, the RouteLink Server only sends the SHA-1 hash knowing that the RouteLink Client already has the full CPR (i.e. sending the CPR would be redundant). The advantage of this approach is that bandwidth for both the RouteLink Client and the RouteLink Server is significantly reduced since a large percentage of CPRs are re-used across CRNs.