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 JSON 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 lastIndex 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 Routeilnk client must assume that there is no more data to currently download, and try again later.
Disclaimer: Any images in this article are intended to be used as a guide for educational purposes only and they may differ slightly from the Production Environment.
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 JSON CPR as well as its SHA-1 hash to the RouteLink Client.
The RouteLnk Client MUST keep track of both the SHA-1 hash and the JSON 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 given the likelihood 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. If, for any reason, the client does not have a matching CPR for the SHA-1 it can be requested via the ‘/cpr?sha1=’ API.
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 JSON 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 lastIndex 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. |