Overview

Root enables you to configure API documentation for your product module using Workbench. This allows you to document your product's customisable API endpoints for any external integrations, for example if you are using an external system to capture quote and application data.

Your product-specific API documentation is accessible under your organisation on Workbench dashboard, together with other important product module information. You can find your API reference by opening your product module on the dashboard and then navigating to "API reference" in the vertical menu on the left of the screen.

Your product-specific API reference exists separately from the documentation for standard (non-configurable) Root endpoints, which is hosted on the Root API reference.

Your product's API docs are configured as a simple array of YAML components. The formatting and display of these components is handled by the dashboard, which expects expects the YAML file to be structured as set out in this guide.

Each component contains one or more key-value pairs. Components can be nested, meaning that the value associated with each key can, in turn, contain a sub-component or array.

1431 — How various YAML components are displayed in your product's API reference on the dashboard.

Endpoint components

Each endpoint is documented as an element in the parent array of the YAML file.

- id: dinosure-quote
  title: Getting a quote
  hideInSidebar: true
  copyComponents:
    ...
  exampleComponents:
    ...

For each customisable endpoint you document, the Root platform expects the same basic component structure. The illustrative examples included in this section are for the quote hook.

The copyComponents property is defined as an array of objects, and is used to define the parameters expected by the endpoint in table format. The exampleComponents property is another array of objects, used to include example requests and responses.

Property	Definition
`id`	string. The unique component identifier. Used to create an anchor link to the relevant section of your API docs.
`title`	string. The heading for this section of your API docs. Typically, this will refer to the specific endpoint. For example, `Getting a quote`.
`hideInSideBar`	boolean. Should be `true`.
`copyComponents`	array of objects. Used to define the API request body parameters. See the `copyComponents` section.
`exampleComponents`	array of objects. Used to provide API request and response examples. See the `exampleComponents` section.

`copyComponents`

copyComponents:
    - type: markdown
      content: >-
        Get a Dinosure quote. The quote parameters will be
        validated when the quote is created.
    - type: list
      title: Body parameters
      content:
        - label: type
          markdownDescription:  >-
            _string_. Product module key, used as the product module identifier. 
            In this case, `dinosure`.
        - label: start_date
        	detail: optional
          markdownDescription: >-
            _string_. Start date for the policy in `YYYY-MM-DD` format.
            If omitted, defaults to the policy issue date.
        - label: cover_amount
          markdownDescription: >-
            _integer_. The cover amount in cents. 
            Must be between `10000000` and `500000000` inclusive.
        - label: age
          markdownDescription: >-
            _integer_. The age of the main member in years. 
            Must be between `18` and `63` inclusive.
        - label: cardio_fitness_level
          markdownDescription: >-
            _string_. The cardio fitness level of the main member. 
            One of `["couch potato", "marathon runner"]`.
        - label: smoker
          markdownDescription: >-
            _boolean_. Whether the main member is a smoker.
        - label: benefits
          markdownDescription: _object_. Optional benefits selected for the policy.
					attributes:
            - label: early_warning_network_benefit
              markdownDescription: >-
              	_boolean_. Whether the customer has selected 
                the early warning network benefit.
            - label: extraction_benefit
              markdownDescription: >-
                _boolean_. Whether the customer has selected the extraction benefit.

This component is used to define the body parameters expected by the endpoint. It is defined as an array of objects, each of which must be of type markdown or list. markdown components render as paragraphs of text, and are typically used to provide additional context to the reader. list components render as tables, and are used to define the request body parameters.

`markdown`

This type of component renders as a paragraph of text, and is typically used to provide context to the reader. For example, additional information required to understand how an endpoint functions, or links to external resources.

Property	Definition
`type`	string. The type of component. In this case, `markdown`.
`content`	string. The text, in markdown format, that will be displayed.

`list`

This component is defined as an array of objects, and renders as a table. It is typically used to define the body parameters expected by the endpoint. For each parameter, this includes the data type, whether it optional, a description, and a list of valid values (where relevant).

The rows of the table are contained under the content property, which is itself defined as an array of objects.

Property	Definition
`type`	string. The type of component. In this case, `list`.
`title`	string. The heading that will be displayed in uppercase above the table. For example, `body parameters`.
`content`	array of objects. Each object in this array will be rendered as a table row. See the `content` section.

`content`

The objects contained in this array are rendered as rows in a two-column table. The label and detail properties are rendered in the left-hand cell, while the markdownDescription is rendered in the right-hand cell. The attributes property can be used to include nested parameters in the same format. Note: Only one level of nesting is supported.

Property	Definition
`label`	string. The key of the relevant body parameter. For example, `start_date`. Renders in the left-hand column of the table.
`detail` optional	string. A subscript that will be included below the row label. Used to designate optional parameters, for example `optional`.
`markdownDescription`	string. This string will be parsed as markdown and displayed in the right-hand column of the table. Used for the definition of the parameter. For example, _string_. Start date for the policy in `YYYY-MM-DD` format..
`attributes` optional	array of objects. This parameter is used to include nested parameters. Object in this array follow the same format as objects in the `content` array. Nested parameters will be rendered as collapsible rows in the table. Note: Only one level of nesting is supported.

`exampleComponents`

exampleComponents:
    - type: code
      blockType: endpoint
      forceLanguage: bash
      languages:
        bash: ...
    - type: code
      blockType: request
      languages:
        curl: ...
    - type: code
      blockType: response
      forceLanguage: json
      languages:
        json: ...

The example components are rendered on the right hand side of the page as code snippets. The example component for each endpoint typically consists of three sub-components:

endpoint - Used to document the URL for the relevant endpoint.
request - Used to include a an example request in CURL format.
response - Used to include an example response in JSON format.

`endpoint`

- type: code
  blockType: endpoint
  forceLanguage: bash
  languages:
    bash: POST https://sandbox.root.co.za/v1/insurance/quotes

This component is used to document the endpoint details, including the request type and URL.

Property	Definition
`type`	string. For all example components this must be `code`.
`blockType`	string. The type of example. In this case, `endpoint`.
`forceLanguage`	string. In this case must be `bash`.
`languages`	object. Must contain a child property, `bash`. The value of this property must contain the request type and URL.

`request`

- type: code
  blockType: request
  languages:
    curl: |-
      curl https://sandbox.root.co.za/v1/insurance/quotes \
      --request POST \
      -u test_key_tYILz1640w9q5n5kNQUZ: \
      -H "Content-Type: application/json" \
      -d '{
              "type": "dinosure",
              "cover_amount": 20000000,
              "age": 30,
              "cardio_fitness_level": "couch potato",
              "smoker": false,
              "benefits": {
                "early_warning_network_benefit": true,
                "extraction_benefit": false
              }
      		}'

This component is used to provide an example of a valid API request to the endpoint.

Property	Definition
`type`	string. For all example components this must be `code`.
`blockType`	string. The type of example. In this case, `request`.
`languages`	object. Must contain a child property, `curl`. The value of this property must be a string representing the API request in cURL format.

`response`

- type: code
  blockType: response
  forceLanguage: json
  languages:
    json: |-
      [
          {
              "quote_package_id": "eacb253d-ebf6-492a-a96c-204978667b9f",
              "package_name": "Dino protection",
              "sum_assured": 20000000,
              "base_premium": 7300,
              "suggested_premium": 7300,
              "module": {
              "cover_amount": 20000000,
              "age": 30,
              "cardio_fitness_level": "couch potato",
              "smoker": false,
              "benefits": {
                  "early_warning_network_benefit": true,
                  "extraction_benefit": false
              },
              "premium_breakdown": {
                  "risk_premium": 7000,
                  "early_warning_network_benefit_premium": 300,
                  "extraction_benefit_premium": 0
              },
              "type": "dinosure"
              },
              "created_at": "2021-12-07T14:12:55.235Z",
              "currency": "ZAR",
              "billing_frequency": "monthly",
              "input_data": {
                  "cover_amount": 20000000,
                  "age": 30,
                  "cardio_fitness_level": "couch potato",
                  "smoker": false,
                  "benefits": {
                    "early_warning_network_benefit": true,
                    "extraction_benefit": false
                  }
            	},
              "product_module_definition_id": "1b1d2c59-fa61-435a-bf0e-23e63dc360ed"
          }
      ]

This component is used to provide an example of a successful response body that can be expected from the endpoint.

Property	Definition
`type`	string. For all example components this must be `code`.
`blockType`	string. The type of example. In this case, `response`.
`forceLanguage`	string. In this case must be `json`.
`languages`	object. Must contain a child property, `json`. The value of this property must be a string representing the API response in JSON format.

Extending API documentation

The examples in this guide refer to the quote hook, which corresponds to the getting-a-quote endpoint for your product module. You can apply the same structure to document any of the other product-specific endpoints configured in your product module. This includes the application hook (create-an-application endpoint), alteration hooks (create-an-alteration-package and apply-alteration-package endpoints).

Each endpoint can be documented as a new component in the array comprising the YAML file. Each element in the array will be displayed below the previous component on the dashboard.

- id: dinosure-quote
  title: Getting a quote
  hideInSidebar: true
  copyComponents:
    ...
  exampleComponents:
    ...
- id: dinosure-application
  title: Creating an application
  hideInSidebar: true
  copyComponents:
    ...
  exampleComponents:
    ...
 - id: dinosure-create-alteration-package
  title: Creating an alteration package
  hideInSidebar: true
  copyComponents:
    ...
  exampleComponents:
    ...
- id: dinosure-apply-alteration-package
  title: Apply alteration package
  hideInSidebar: true
  copyComponents:
    ...
  exampleComponents:
    ...

You could also adapt this structure to document the API endpoints for updating and retrieving claims block states from an external system as part of the claims workflow.