Advice Content Types
Using an Accept header to request a specific content format.
Our RESTful API understands and communicates in JSON. Consumers must send the Accept
header with the desired and appropriate MIME type.
Advice Formats
The API will always return JSON but the Advice content contained within can be plain text, plain text with AttributedString definitions, or HTML. Markdown is coming soon.
Since the API always returns JSON, the default Content-Type is application/json
. In the default configuration, plain text will be the format for Advice content fields (which include question
, explanation
, headline
, summary
, etc.).
To change the format of the Advice content within the API, use a custom Accept
header as demonstrated below.
Plain Text (default)
The following MIME types (including the two custom ones) are equivalent for retrieving plain text.
Accept: application/json
Accept: application/vnd.taffrail.json
Accept: application/vnd.taffrail.json+text <- preferred
Example of plain text Advice using this header:
{
"headline": "Because your income is above $198,000, you are not eligible for a Roth IRA and should consider a Traditional IRA instead."
}
Plain Text with AttributedString Support
To request text with a list of attributions for use in AttributedString structs (found in iOS and Android, among others), use the +attrstring
modifier on the Accept
header as follows. Note that the plain text field will always be returned, and a new [field]_attributes
field appears.
Accept: application/vnd.taffrail.json+attrstring
Example of Advice using this header illustrating a Backlink attribution:
{
"headline": "Because your income is above $198,000, you are not eligible for a Roth IRA and should consider a Traditional IRA instead."
"headline_attributes": [{
"range": {
"indexStart": 8,
"indexEnd": 37,
"length": 29
},
"variable": "Roth_Income_Menu_Single",
"value": "your income is above $198,000",
"type": "backlink",
"id": "oRzEh5HLrP8i3c_PXltzV"
}]
}
Notes on the [field]_attribution
objects:
- The
range
property's object contains the start, end, and length of the attribution. - The
id
property's value is the Variable ID, for cross-referencing the Variables list. - If a
type
property exists in the[field]_attributes
items, its value will be eitherformat
,backlink
, orformulaic
. - If there are no attributions in a string, the
[field]_attributes
property will not exist.
Formats & Backlinks
Formatted Text
If the [field]_attributes
property contains an entry with"type": "format"
, that indicates a fragment should be formatted according to the value of the format
property. See below for an example.
Theformat
property value is an enum of bold
, italic
, and indeterminate
.
Example of an Input Request using this header illustrating a Format attribution:
{
"question": "How much are your **monthly** living expenses?"
"question_attributes": [{
"range": {
"indexStart": 18,
"indexEnd": 25,
"length": 7
},
"format": "bold",
"value": "monthly",
"type": "format"
}]
}
Backlinks
If the [field]_attributes
property contains an entry with"type": "backlink"
, that indicates a phrase is associated with a Variable in an Input Request. In the example further above, "income is above $198,000" would be linked to the Input Request that assigns Roth_Income_Menu_Single
.
If the type
is formulaic
, that indicates a Variable was found in the string and it does not have an associated Input Request. You can choose to attribute or style the Variable, or not.
Backlinks
A Backlink is used to link a Variable in Advice text to the assumption (or originating question) where the user could modify the input.
Read more about Backlinks.
HTML
To request formatted HTML, use the +html
modifier on the Accept
header as follows. Note that the plain text field will always be returned, and a new _html
field appears.
Accept: application/vnd.taffrail.json+html
Example of Advice using this header.
{
"headline": "Because your income is above $198,000, you are not eligible for a Roth IRA and should consider a Traditional IRA instead."
"headline_html": "Because <a href=\"#Roth_Eligibility\" data-variable-id=\"EbAx0DxX9Bm490AALrEPV\" class=\"taffrail-var\"><taffrail-var data-type=\"Freetext\" data-variable-name=\"Roth_Eligibility\" data-variable-id=\"EbAx0DxX9Bm490AALrEPV\" data-raw-value=\"Income too high for a Roth\">your income is above <taffrail-var data-type=\"Number\" data-format=\"$0,0\" data-variable-name=\"IRS_Limit_Roth_MFJ_Income_Low\" data-variable-id=\"Bj09EXCZkhOiKxdsa4UaL\" data-raw-value=\"198000\">$198,000<\/taffrail-var><\/taffrail-var><\/a>, you are not eligible for a Roth IRA and should consider a Traditional IRA instead.\n"
}
If the HTML response includes a hyperlinked element, that indicates the linked phrase is associated with a Variable in an Input Request. In the example above, "your income is above $198,000" would be linked to the Input Request that assigns Roth_Eligibility
.
It is the responsibility of the HTML renderer to attach appropriate interface events to show the linked Input Request to the user.
Backlinks
A Backlink is used to link a Variable in Advice text to the assumption (or originating question) where the user could modify the input.
Read more about Backlinks.
HTML without hyperlinks
It is possible to request Advice content formatted as HTML explicitly without hyperlinked Backlinks. This is commonly used for printing tearsheets or static PDF generation where hyperlinks detract from the final product.
To request formatted HTML, use the +htmlnolinks
modifier on the Accept
header as follows. Note that the plain text field will always be returned, and a new _html
field appears.
Accept: application/vnd.taffrail.json+htmlnolinks
Markdown
Unparsed (raw) Markdown syntax support is coming in a future release.
Raw
To request unformatted raw Advice content without variable values resolved, use the +raw
modifier on the Accept
header as follows. This format is only useful when debugging or when implementing a custom interface and parsing engine.
Accept: application/vnd.taffrail.json+raw
Example of Advice using this header.
{
"headline": "Because your income is above {{IRSLimitRothMFJIncome_Low}}, you are not eligible for a Roth IRA and should consider a Traditional IRA instead."
}
Updated 5 months ago