🖼️
KASKO Frontend Documentation
  • README
  • Getting started
    • Setting up a new webapp
    • Webapp manifest
    • Building the flow
    • Defining layouts
    • Defining computed values
    • Defining dynamic paths
  • Core concepts
    • Forms
    • Validation
      • Using existing validators
      • Adding custom validators
    • Configuration
      • Price format
      • Date format
    • Performing API calls
    • Toggling visibility of components
    • Translations
    • Rules For Robust Application
  • Guides
    • Using logical statements (JsonLogic)
    • Adding discount codes
    • Developing Custom Plugins
    • Setting required requests
    • Adding save quote for later
    • Transforming request data
    • Manifest merging strategy
    • Knockout flow
    • Local pricing logic
    • Setting up dashboard policy profile
    • Handling offers
    • Repeater
  • Snippets
    • Reset input state
  • Useful resources
    • All component descriptions
    • JsonLogic core documentation
    • Kasko.js documentation
    • Example webapp
    • Example plugins (w/ various frameworks)
Powered by GitBook
On this page
  • Field Definitions
  • Backend Field Definitions
  • Frontend Field Definitions
  • Defining Triggered Requests In The Manifest
  • Transforming Customer Input Before Sending To API
  1. Core concepts

Performing API calls

Last updated 21 days ago

Each application must perform a multitude of requests. The most common ones are:

  • quote - to retrieve the price by the given custom input arguments;

  • policy - to create a offer (unpaid policy);

  • payment - to process a payment;

  • lead - to create a lead object (usually used for save-for-later functionality);

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 . 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.

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.

interface EnabledRequest {
  type: string; // unique identifier of the request (quote, policy, payment, lead)
  version?: 'v1' | 'v2'; // version for the API; default: v1; most commonly used these days: 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": "required_true"
      }
    ]
  },
  {
    "type": "payment"
  }
]

Transforming Customer Input Before Sending To API

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

Request definition is done in the config section.

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

validation rules
manifest
manifest
request transformation guide