Specification
Feed Endpoint
The feed endpoint must have the following properties:
- Must use the HTTP "GET" method.
- Must return "content-type: application/json" HTTP header.
- Must allow query parameters (a "delta" query param will be appended to feed URL)
- Must have CORS enabled (in order to bypass cross-domain restrictions on WebApps)
The feed endpoint should have the following properties (see Best Practices):
- Should use minified JSON
- Should support GZip compression
- Should make use of the "delta" query parameter
Endpoint Payload
The feed payload must conform to the following JSON Schema:
{
"title": "Recurr",
"type": "object",
"required": [
"protocol",
"version",
"title",
"caption"
],
"properties": {
"protocol": {
"type": "string",
"description": "Protocol Identifier (must be 'recurr')",
"enum": [
"recurr"
]
},
"version": {
"type": "number",
"description": "Version of Recurr Protocol (should be 1.0)"
},
"title": {
"type": "string",
"description": "Feed title (usually name of your service)"
},
"caption": {
"type": "string",
"description": "Feed caption (usually the account name or account identifier)"
},
"bills": {
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/bill"
},
"description": "List of bill items keyed by Bill ID"
},
"balances": {
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/balance"
},
"description": "List of balance items keyed by Balance ID"
},
"receipts": {
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/receipt"
},
"description": "List of receipt items keyed by Receipt ID"
},
"actions": {
"type": "array",
"items": {
"$ref": "#/$defs/action"
},
"description": "Global actions that can be performed on Feed (e.g. 'Manage Account')"
},
"redirect": {
"type": "string",
"description": "This can be used to update the feed endpoint (e.g. if the URL has changed)"
},
"merge": {
"type": "object",
"description": "Determines how the feed should be merged (only 'shallow' currently supported)",
"properties": {
"bills": {
"type": "string",
"description": "Title of the action",
"enum": [
"set"
],
"default": "set"
},
"balances": {
"type": "string",
"description": "URL that will be triggered upon click",
"enum": [
"set"
],
"default": "set"
},
"receipts": {
"type": "string",
"description": "URL for icon",
"enum": [
"set"
],
"default": "set"
}
}
}
},
"$defs": {
"action": {
"type": "object",
"required": [
"title",
"url"
],
"properties": {
"title": {
"type": "string",
"description": "Title of the action"
},
"url": {
"type": "string",
"description": "URL that will be triggered upon click"
},
"icon": {
"type": "string",
"description": "URL for icon"
}
}
},
"bill": {
"type": "object",
"required": [
"title",
"amount",
"currency",
"due",
"actions"
],
"properties": {
"title": {
"type": "string",
"description": "Title of bill item (e.g. October 2021)"
},
"amount": {
"type": "number",
"description": "Amount that is due"
},
"currency": {
"type": "string",
"description": "Currency code that amount is in"
},
"due": {
"type": "string",
"description": "Due date of bill formatted as an ISO8601 Date String"
},
"actions": {
"type": "array",
"items": {
"$ref": "#/$defs/action"
},
"description": "Array of actions that can be performed on this Item"
}
}
},
"balance": {
"type": "object",
"required": [
"title",
"amount",
"low",
"currency",
"actions"
],
"properties": {
"title": {
"type": "string",
"description": "Title of the balance item (e.g. 'Available Balance')"
},
"amount": {
"type": "number",
"description": "The current balance amount"
},
"low": {
"type": "number",
"description": "The amount when balance should be considered low"
},
"currency": {
"type": "string",
"description": "The currency code that 'amount' and 'low' are specified in"
},
"actions": {
"type": "array",
"items": {
"$ref": "#/$defs/action"
},
"description": "Array of actions that can be performed on this Item"
}
}
},
"receipt": {
"type": "object",
"required": [
"title",
"amount",
"currency",
"paid",
"actions"
],
"properties": {
"title": {
"type": "string",
"description": "Title of the receipt (e.g. 'October 2021')"
},
"amount": {
"type": "number",
"description": "The total amount that was paid"
},
"currency": {
"type": "string",
"description": "The currency code that the amount is in"
},
"due": {
"type": "string",
"description": "Due date of bill (if available) formatted as an ISO8601 Date String"
},
"paid": {
"type": "string",
"description": "Paid date of bill formatted as an ISO8601 Date String"
},
"actions": {
"type": "array",
"items": {
"$ref": "#/$defs/action"
},
"description": "Array of actions that can be performed on this Item"
}
}
}
}
}
