Performing API calls

Each application must perform a multitude of requests. The following request types are available:

Request Types

Webapp/Policy Mode

Type	Description
quote	Retrieve the price by the given customer input arguments. Price-affecting fields.
quote_patch	Modify an existing quote (MTA flow).
policy	Create an offer (unpaid policy). Non-price-affecting fields.
policy_patch	Modify an existing policy (MTA - Mid-Term Adjustment).
payment	Process a payment.
lead	Create a lead object (usually used for save-for-later functionality).
save_quote_for_later	Save quote for later functionality.
discount	Apply discount/coupon codes.
idd	Insurance Distribution Directive related data.

Claims/FNOL Mode

Type	Description
claim	Submit claim details. ALL fields in FNOL mode use this type.
otp_fnol	OTP login fields for FNOL authentication.

Claim updates reuse claim fields with editable set (there is no distinct claim_patch type).

Internal Types

Type	Description
internal_quote	Internal quote requests (v1 API).
quote_internal	Internal quote requests (v2 API).
lead_challenge	Lead challenge/verification.

quote, policy and lead requests are performed as soon as all the required information has been collected from the customer. Whereas payment request is triggered only after clicking a predefined button.

But how can the required pieces of information that must be collected set? Read on for more information.

Field Definitions

Backend Field Definitions

If an API needs to be built, the API needs to know what pieces of information it can expect. It must also know the validation rules. This is done via the field definitions.

The backend field definitions are also used to validate the data in frontend. Though even if the dataset is not fully-valid, it may be still sent to backend (and there rejected). This is because there are some specific backend-only validation rules which frontend simply cannot do (like checking MX records of an email domain).

Dataset is sent to backend if all required validation rules are passing.

interface FieldDefinition {
  path: string; // "path" to the field (if object is deeply nested)
  name: string; // unique name of the field
  validation: string; // validation rules for the field
}

For example, given this field definition:

[
  { "path": "", "name": "first_name", "validation": "required|string" },
  { "path": "", "name": "last_name", "validation": "required|string" },
  { "path": "data", "name": "duration", "validation": "required|string|in:P1Y,P2Y" }
]

Backend knows that the expected input will be something like this:

{
  "first_name": "John",
  "last_name": "Doe",
  "data": {
    "duration": "P1Y"
  }
}

Field Definition Versions

Backend Field Definition currently supports two versions: 1.0 and 2.0

{
  "version": "1.0" | "2.0"
  "definition": [...]
}

The main difference between these two is the definition enforcement of quote and quote_patch sections. The important changes are listed below:

• Thequote and quote_patch sections must have path property prefixed with data value.

• The constraints where dynamic values are used (i.e. required_if etc.) must have the data prefix as well in order for them to work properly (i.e. required_if:data.bad_weather,true).

This is done to ensure consistency with all the other definition sections and remove any possible confusion as quote requests do not have root level properties available for validation.

So given this quote request payload to backend API:

https://api.eu1.kasko.com/quotes
{
   "data": {
        "field_1": false,
        "nested": {
            "field_2": 123
        }
   }
   ...
}

The field definition must look like this:

{
  "quote": [
    {
      "path": "data",
      "name": "field_1",
      "validation": "required|boolean"
    },
    {
      "path": "data.nested",
      "name": "field_2",
      "validation": "required_if:data.field_1,true|integer"
    }
  ]
}

The full JSON Schema of the Backend Field Definition can be viewed here: https://github.com/kasko/php-field-definition-lib/blob/master/src/Schema/schema.json

Frontend Field Definitions

Sometimes there are some things that need to be validated purely in the frontend and that must not be sent to the API. For example, this could be the acceptance to the privacy policy. Even though it must be validated that the customer has accepted it, the boolean data must not be sent to backend.

In this case, the rule for the privacy policy field sits in the frontend field definitions. The structure is exactly the same as the backend field definitions. Difference is in the location.

Backend field definitions sit in root level of a product (i.e. in a separate field). Whereas the frontend field definitions sit within the manifest config section.

Defining Triggered Requests In The Manifest

The application must always know all the requests that it will need to trigger. If no requests have been configured - none will be triggered.

Request definition is done in the manifest config section.

interface EnabledRequest {
  type: string; // unique identifier of the request (see Request Types above)
  version?: 'v1' | 'v2' | 'v3'; // version for the API; default: v1; most commonly used: v2
  field_definition?: FieldDefinition[];
  transformer?: RequestTransformer[];
}

Example request definition:

[
  {
    "type": "quote",
    "version": "v2"
  },
  {
    "type": "policy",
    "version": "v2",
    "field_definition": [
      {
        "path": "data",
        "name": "data_privacy",
        "validation": "accepted"
      }
    ]
  },
  {
    "type": "payment"
  }
]

Transforming Customer Input Before Sending To API

This is a rather tricky topic which deserves a page of its own. See the request transformation guide for more information.