API docs
Document your product module's customisable API endpoints
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.
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
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
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
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
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
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
endpoint
- type: code
blockType: endpoint
forceLanguage: bash
languages:
bash: POST https://sandbox.rootplatform.com/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
request
- type: code
blockType: request
languages:
curl: |-
curl https://sandbox.rootplatform.com/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
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.
Updated 5 months ago