From the beginning, most of the API exposed via our policy-related services has been map-based. Gradually, we found that such map-based APIs are sometimes not easy to use, so we decided to replace them with domain-based APIs.
This document offers a detailed explanation of the differences between map APIs and domain APIs. While map-based APIs will not be removed, it is strongly recommended to use policy core APIs instead of map APIs.
Strength for Domain API against Map API
While using the RESTful API, users may not readily perceive the distinction between domain API and map API. However, when writing code with the SDK, domain API offer enhanced support in terms of both documentation and maintainability compared to map API.
- Map API
Users can treat it as a Map and use Map operator to add anything into policy object.
- Domain API
When adding content to the policy, users may choose from the following options:
- Transform it to a Map using JSONUtils and perform standard Map operations.
- Utilize specialized entity lookup mechanism to directly add models without converting to a Map.
For details about how to use entity lookup mechanism, users can refer to Welcome to InsureMO SDK for Java.
API Payload Comparison
From the restful API prospective, there’s little difference between domain and map API. However, the most significant distinction lies in the following aspects:
- Domain API: Requires @type and businessObjectId in all requests and returns them in responses.
- Map API: Excludes @type and businessObjectId from both requests and responses.
To prevent compatibility problems when switching APIs due to differences, special provisions have been implemented to ensure:
- Domain API: Accepts requests without @type and businessObjectId.
- Map API: Accepts requests with @type and businessObjectId.
In conclusion, due to the compatibility that has been achieved, users can freely switch between them.
API List Comparison
The following table outlines the relationship between Map and Core APIs for the most frequently used APIs.
For a complete list of available APIs, refer to the InsureMO API documentation.
| Action | Quotation Map API | Quotation Domain API | Proposal Map | Proposal Domain API | Endo Map API | Endo Domain API |
|---|---|---|---|---|---|---|
| Create | /quotation/v1/persist | /quotation/core/quotation/v1/create | /proposal/v1/create | /proposal/core/proposal/v1/createEx | /endo/v1/create | /endo/core/endo/v1/createEx |
| Update | /quotation/v1/persist | /quotation/core/quotation/v1/update | /proposal/v1/save | /proposal/core/proposal/v1/updateEx | /endo/v1/save | /endo/core/endo/v1/updateEx |
| Issue | N/A | N/A | /proposal/v1/issuePolicy | /proposal/core/proposal/v1/issuePolicyEx | /endo/v1/issueEndorsement | /endo/core/endo/v1/issueEndorsementEx |
| Load | /quotation/v1/load | /quotation/core/quotation/v1/load | /proposal/v1/load | /proposal/core/proposal/v1/load | /endo/v1/load | /endo/core/endo/v1/load |
| Calculate | /quotation/v1/quotation | /quotation/core/quotation/v1/calculate | /proposal/v1/calculate | /proposal/core/proposal/v1/calculateEx | /endo/v1/calculate | /endo/core/endo/v1/calculateEx |
| Underwriting | /quotation/v1/underwriting | /quotation/core/quotation/v1/autoUnderwriting | /proposal/v1/underwriting | /proposal/core/proposal/v1/autoUnderwriting | /endo/v1/underwriting | /endo/core/endo/v1/autoUnderwriting |
| Validate | /quotation/v1/validate | /quotation/core/quotation/v1/validate | /proposal/v1/validate | /proposal/core/proposal/v1/validate | /endo/v1/validate | /endo/core/endo/v1/validateEx |
| Attach element | /quotation/v1/attachElement | /quotation/core/quotation/v1/attachElement | /proposal/v1/attachElement | /proposal/core/proposal/v1/attachElement | /endo/v1/attachElement | /endo/core/endo/v1/attachElement |
| More than 1 above step | - | - | /proposal/v1/process | /proposal/core/proposal/v1/process | /endo/v1/process | /endo/core/endo/v1/process |