The /sync endpoints

Every line of business has a set of /sync... endpoints that can address issues with out-of-sync data. The following sections cover each set of endpoints and what how they synchronize data.

The /sync-coverages endpoints

An LOB can have the following /sync-coverages endpoints:

  • POST /jobs/{jobId}/lines/{lineId}/sync-coverages
  • POST /jobs/{jobId}/lines/{lineId}/{coverableName}/{coverableId}/sync-coverages

Note that coverages can be nested. For a given line of business, there could be a POST that starts with POST /jobs/{jobId}/lines/{lineId}/{coverableName}/{coverableId}, which is then followed by one of more instances of /{coverableName}/{coverableId} before terminating with /sync-coverages.

Generating the endpoints

During code generation, APD adds these endpoints to every coverable, including the line itself (if it is a coverable).

Endpoint behavior

When you execute a POST /sync-coverages, Cloud API:

  • Adds missing available-and-required coverages, conditions, and exclusions
  • Removes unavailable coverages, conditions, and exclusions
  • Adds missing covterms to coverages, conditions, and exclusions
  • Removes unavailable covterms from coverages, conditions, and exclusions
  • Resets the value if a covterm has an unavailable option, unavailable package, or unavailable or retired typekey as its current value. (The value is set to the default, or null if there is no default.)

The /sync-fields endpoints

An LOB can have the following /sync-fields endpoints:

  • POST /jobs/{jobId}/lines/{lineId}/sync-fields
  • POST /jobs/{jobId}/lines/{lineId}/{coverableName}/{coverableId}/sync-fields
  • POST /jobs/{jobId}/lines/{lineId}/.../{exposureName}/{exposureId}/sync-fields

Generating the endpoints

During code generation, APD adds these endpoints to every coverable (including the line itself) and every exposure that meet the following conditions:

  • The coverable or exposure already exists in the data model and the corresponding data model entity implements the SyncableAdapter interface, or
  • The coverable or exposure does not already exist in the data model. (This occurs when you are generating entities and endpoints at the same time for a new APD line).

If the data model entity for the coverable of exposure does not implement the SyncableAdapter interface, the /sync-fields endpoints are not generated. This can occur in the following circumstances:

  • In some releases prior to the current release, Cloud API did not add the SyncableAdapter interface to new coverables and exposures. Thus, the code generation for those releases did not create /sync-fields endpoints. (Regenerating the LOB-specific endpoints on the current release will most likely generate the /sync-fields endpoints.)
  • Lines of business that are not native to APD (such as base configuration LOBs or SBT lines) typically have coverables and exposures that do not implement the SyncableAdapter interface. Therefore, LOB-specific endpoints for these LOBs do not have /sync-fields endpoints.

Endpoint behavior

When you execute a POST /sync-fields, Cloud API:

  • "Adds" missing available fields
  • "Removes" unavailable fields
  • Nulls out the value of any fields that have unavailable typekeys as their value

The /sync-modifiers endpoints

An LOB can have the following /sync-modifiers endpoints:

  • POST /jobs/{jobId}/lines/{lineId}/sync-modifiers
  • POST /jobs/{jobId}/lines/{lineId}/{coverableName}/{coverableId}/sync-modifiers
  • POST /jobs/{jobId}/lines/{lineId}/.../{exposureName}/{exposureId}/sync-modifiers

Generating the endpoints

During code generation, APD adds these endpoints to every coverable that meets one of the following conditions:

  • The coverable is already declared in the data model and the data model entity implements the Modifiable interface, or
  • The coverable is part of a product that was originally designed outside of APD (such as a base configuration product or a product from a Standards-Based Template).

These endpoints are added for installed products only. They are not present for visualized products.

Endpoint behavior

When you execute a POST /sync-modifiers, Cloud API:

  • Adds missing available modifiers
  • Removes unavailable modifiers
  • Updates the state on modifiers to make sure it matches the state of the parent entity
  • Adds missing available rate factors to modifiers
  • Removes unavailable rate factors from modifiers

The /sync-questions endpoints

An LOB can have the following /sync-questions endpoints:

  • POST /jobs/{jobId}/sync-questions
  • POST /jobs/{jobId}/lines/{lineId}/sync-questions
  • POST /jobs/{jobId}/locations/{locationId}/sync-questions

There can also be /sync-questions endpoints for any coverable or exposure that has been made an AnswerContainer.

Generating the endpoints

In the base configuration, these endpoints already exist for the job itself and for policy locations.

During code generation, APD adds endpoints to:

  • Every location-based coverable
    • This type of endpoint is essentially proxy for calling /sync-questions on the linked policy location.
  • Every policy line, because the base configuration PolicyLine entity implements the AnswerContainer interface
  • Any other coverables or exposures that are already declared in the data model and the data model entity implements the AnswerContainer interface

These endpoints are added for installed products only. They are not present for visualized products.

Endpoint behavior

When you execute a POST /sync-questions, Cloud API:

  • Adds answer entities to hold the answer for any missing available questions
  • Removes answers for any unavailable questions

When to call a /sync endpoint

The need to sync coverables, coverages, modifiers, or questions depends on the structure of the LOB and the order in which a given caller application makes changes. Therefore, it is up to the caller application to determine when a /sync endpoint must be called. Note the following:

  • From a data integrity standpoint, there is no harm in calling a /sync endpoint, even when all information is already in sync.
  • From a performance standpoint, calling a /sync endpoint does require system resources. A caller application's performance could be compromised unnecessarily if it makes repeated calls to /sync endpoints when the coverage data is already in sync.

As an alternative to synchronizing job data, you can also defer validation. For more information, see Deferring validation.

Syncing child objects

When you use any of the /sync endpoints to synchronize data, only the top-level objects are synchronized. Synchronization does not affect any children of the synchronized objects, and it does not affect other attached objects. To synchronize nested child objects across the policy hierarchy, you must make additional calls targeting those child objects.

For example, a line-level coverage can have child coverages. When you call the POST /jobs/{jobId}/lines/{lineId}/sync-coverages endpoint, only the line-level coverages are synced. To sync the child coverages, you must make additional calls using endpoints such as POST /jobs/{jobId}/lines/{lineId}/{coverableName}/{coverableId}/sync-coverages.

This behavior applies across all /sync endpoints.