Performing API calls

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

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