Initialization
When a RouteLink Client registers with the RouteLink service, the RouteLink Server resets the RouteLink Client's status to download from beginning. Please Note: the CPR data will be sent first as a "cpr" event followed by the CRN data as "add" events. The CPR records contain a hash value and any CRN that uses that CPR will also contain the same hash value in its "add" event record. Once the initial "add" events are downloaded, all subsequent downloads are changes in CRN state ("add" and "delete" events). The initial load is composed of millions of events, but this initialization only has to occur once for the new RouteLink Client.
In the case where the RouteLink Client has an unrecoverable failure, it may need to reset all of its data and "start over". It is left to the RouteLink Server discretion to refuse an unexpected initialization request (for example the RouteLink Server could limit initializations to being accessible only after manual intervention indicates it is allowed for a RouteLink Client).
The RouteLink Client communicates an initialize request to the server using the following URL:
/routelink/v1/initialize
The RouteLink Server can issue a success or failure response. The failure response follows the same rules as presented in the Chapter titled, "Error Detection" located within this document. The success JSON response is as follows:
{ "result": "success" } // See Error Detection section for errors
Failure responses are left to the RouteLink Server's discretion but could include a rejection due to too many initializations being requested. The error message format is described in the Chapter titled, "Error Detection" located within this document. During the "official" certification process, a full download of all data must be performed and requests for a single NPA will result in an error response. A success reply will initiate logic at the RouteLink Server to prepare the download data for the RouteLink Client. The following is an example of steps that make up the initialize process:
- The RouteLink Client clears its DB of all CRNs.
- The RouteLink Client sends the initialize request.
- The RouteLink Server resets the RouteLink Client's status to begin the download.
- The RouteLink Client should periodically call the /routelink/v1/download URL and data will be sent once it is available.
- If the RouteLink Client sends the lastIndex parameter as part of the download command, use a value of zero following the call to initialize.
- The RouteLink Client, after downloading all the "cpr" and "add" events from its event queue, continues to receive new download events from the ongoing events that occurred during initialize process.
- When the RouteLink Client consumes the last record from the initialization and starts receiving real-time updates, a large jump in the last Index value is expected (i.e. greater than 1 million).
Please Note: We are not taking the snapshot of DB for initializing the RouteLink Client. Real time updates happen on RouteLink during RouteLink Client’s initialize process. We suggest the RouteLink Client to have the referential integrity between crn’s sha and cpr’s sha so you will know if there is a new sha value during your initialize process.
If you find sha1 but there is no "cpr" in your DB, you can either reject that message or use /cpr API to get the latest "cpr" for that sha1 value. Please refer to the Chapter titled, "CPR API" in this document for /cpr API details.
If you reject the message, make sure you are consuming it through live updates. While consuming live updates, if you see CPR value in your response, that indicates a new "cpr". If "cpr" is null, that shows it is already existing.
If the RouteLink Server fails to initialize for any reason it returns a failure response. The RouteLink Client is free to retry later if the failure is temporary. Please refer to the Chapter titled, "Error Detection" in this document to determine if an error is temporary or permanent.
Initialization Message Details
The following section describes the JSON format of the "cpr" message. Once all of the CPR messages are downloaded by the API client, "add" events for each call routing number will follow. The RouteLink Client should expect to receive more than 250,000 "cpr" messages and over 40 million "add" messages. RouteLink Client can download only 1,000 CPR messages at one time.
{
"events":[
{
"action":"cpr",
"sha1":"<40 chars>",
"cpr":"<variable length base64 encoded CPR>",
"id": 1000
},
{
"action":"cpr",
"sha1":"<40 chars>",
"cpr":"<variable length base64 encoded CPR>"
"id": 1000
} ] }