performance.json

{
    "title": "Performance",
    "category": "derived",
    "docpath": "performances",
    "introduction": [
        "A Performance is a hierarchical collection of <a class=\"link\" href=\"/documentation/accounts\">Account</a> balances describing the financial performance of an <a class=\"link\" href=\"/documentation/entities\">Entity</a> over a period of time. They are generic representations of popular accounting constructs known as the 'Income Statement', 'Profit & Loss', or 'Statement of Financial Performance'.",
        "The Peformance object is jurisdiction agnostic, and obeys simple double-entry accounting rules. They list income and expense, each nesting its own children.",
        "You can retrieve a Performance denominated in an arbitrary <a class=\"link\" href=\"/documentation/unit\">Global Unit</a> or <a class=\"link\" href=\"/documentation/custom_unit\">Custom Unit</a>. Amatino will automatically calculate the implicit gain or loss relative to each Account's underlying denomination and include those gains and losses in each Account balance.",
        "A Performance may be retrieved to an arbitrary depth. Depth in the Performance context is the number of levels down the Account hierarchy Amatino should go when retrieving the Performance. For example, if a top-level Account has child accounts three layers deep, then specifying a depth of three will retrieve all those children.",
        "Regardless of the depth you specify, Amatino will calculate recursive balances at full depth."
    ],
    "object": {
        "name": "Performance",
        "exposition": "Performance objects are returned with the following structure",
        "form": {
            "root": "object",
            "components": [
                {
                    "key": {
                        "value": "\"entity_id\"",
                        "mono": true
                    },
                    "type": {
                        "value": "JSON String",
                        "mono": false
                    },
                    "description": {
                        "value": "The identifer of the <a class=\"link\" href=\"\\documentation\\entities\">Entity</a> this Performance describes",
                        "mono": false
                    },
                    "example": {
                        "value": "\"oB3cjSNKXklkJ4Tb\"",
                        "mono": true
                    }
                },
                {
                    "key": {
                        "value": "\"start_time\"",
                        "mono": true
                    },
                    "type": {
                        "value": "JSON String",
                        "mono": false
                    },
                    "description": {
                        "value": "Beginning of the period over which performance is measured, in the format YYYY-MM-DD_HH24:MI:SS.US, in UTC.",
                        "mono": false
                    },
                    "example": {
                        "value": "\"2017-01-01_00:00:00.00000\"",
                        "mono": true
                    }
                },
                {
                    "key": {
                        "value": "\"end_time\"",
                        "mono": true
                    },
                    "type": {
                        "value": "JSON String",
                        "mono": false
                    },
                    "description": {
                        "value": "End of the period over which performance is measured, in the format YYYY-MM-DD_HH24:MI:SS.US, in UTC.",
                        "mono": false
                    },
                    "example": {
                        "value": "\"2018-01-01_00:00:00.00000\"",
                        "mono": true
                    }
                },
                {
                    "key": {
                        "value": "\"generated_time\"",
                        "mono": true
                    },
                    "type": {
                        "value": "JSON String",
                        "mono": false
                    },
                    "description": {
                        "value": "Time that this Performance was computed, in the format YYYY-MM-DD_HH24:MI:SS.US, in UTC",
                        "mono": false
                    },
                    "example": {
                        "value": "\"2018-05-02_05:01:54.72941\"",
                        "mono": true
                    }
                },
                {
                    "key": {
                        "value": "\"global_unit_denomination\"",
                        "mono": true
                    },
                    "description": {
                        "value": "The id of the global unit in which this Performance is denominated, if applicable",
                        "mono": false
                    },
                    "type": {
                        "value": "JSON Number or JSON Null",
                        "mono": false
                    },
                    "example": {
                        "value": "5",
                        "mono": true
                    }
                },
                {
                    "key": {
                        "value": "\"custom_unit_denomination\"",
                        "mono": true
                    },
                    "description": {
                        "value": "The id of the custom unit in which this Performance is denominated, if applicable.",
                        "mono": false
                    },
                    "type": {
                        "value": "JSON Number or JSON Null",
                        "mono": false
                    },
                    "example": {
                        "value": "null",
                        "mono": true
                    }
                },
                {
                    "key" :{
                        "value": "\"income\"",
                        "mono": true
                    },
                    "description": {
                        "value": "A list of <a class=\"link\" href=\"/documentation/trees/node\">Tree Node</a> objects representing income Accounts",
                        "mono": false
                    },
                    "type": {
                        "value": "JSON Array",
                        "mono": false
                    },
                    "list objects": {
                        "value": "Tree Node",
                        "mono": false,
                        "link": "/documentation/trees/node"
                    },
                    "example": {
                        "value": "See <a href=\"/documentation/trees/node\" class=\"link\">Tree Nodes</a>",
                        "mono": false
                    }
                },
                {
                    "key" :{
                        "value": "\"expenses\"",
                        "mono": true
                    },
                    "description": {
                        "value": "A list of <a class=\"link\" href=\"/documentation/trees/node\">Tree Node</a> objects representing expense Accounts",
                        "mono": false
                    },
                    "type": {
                        "value": "JSON Array",
                        "mono": false
                    },
                    "list objects": {
                        "value": "Tree Node",
                        "mono": false,
                        "link": "/documentation/trees/node"
                    },
                    "example": {
                        "value": "See <a href=\"/documentation/trees/node\" class=\"link\">Tree Nodes</a>",
                        "mono": false
                    }
                },
                {
                    "key" :{
                        "value": "\"depth\"",
                        "mono": true
                    },
                    "description": {
                        "value": "The maximum Account depth to which this Performance recurses",
                        "mono": false
                    },
                    "type": {
                        "value": "JSON Number",
                        "mono": false
                    },
                    "example": {
                        "value": "3",
                        "mono": true
                    }
                }
            ]
        }
    },
    "actions": [
        {
            "name": "Retrieve",
            "method": "GET",
            "path": "/performances",
            "description": "Retrieve a Performance",
            "return_root_type": "JSON Object",
            "required_json_data": {
                "root": "object",
                "components": [
                    {
                        "key": {
                            "value": "\"start_time\"",
                            "mono": true
                        },
                        "type": {
                            "value": "JSON String",
                            "mono": false
                        },
                        "description": {
                            "value": "Beginning of the period over which performance is measured, in the format YYYY-MM-DD_HH24:MI:SS.US, in UTC, exclusive (>)",
                            "mono": false
                        },
                        "example": {
                            "value": "\"2017-01-01_00:00:00.00000\"",
                            "mono": true
                        }
                    },
                    {
                        "key": {
                            "value": "\"end_time\"",
                            "mono": true
                        },
                        "type": {
                            "value": "JSON String",
                            "mono": false
                        },
                        "description": {
                            "value": "End of the period over which performance is measured, in the format YYYY-MM-DD_HH24:MI:SS.US, in UTC, inclusive (<=)",
                            "mono": false
                        },
                        "example": {
                            "value": "\"2018-01-01_00:00:00.00000\"",
                            "mono": true
                        }
                    },
                    {
                        "key": {
                            "value": "\"global_unit_denomination\"",
                            "mono": true
                        },
                        "description": {
                            "value": "The id of the global unit denomination in which you would like to view the Tree. Specify either global or custom unit denomination.",
                            "mono": false
                        },
                        "type": {
                            "value": "JSON Number or JSON Null",
                            "mono": false
                        },
                        "example": {
                            "value": "5",
                            "mono": true
                        },
                        "source": {
                            "value": "/units/list",
                            "mono": false,
                            "link": "/documentation/unit_list"
                        }
                    },
                    {
                        "key": {
                            "value": "\"custom_unit_denomination\"",
                            "mono": true
                        },
                        "description": {
                            "value": "The id of the custom unit in which you would like to view the Ledger, if desired. Specify either global or custom unit denomination",
                            "mono": false
                        },
                        "type": {
                            "value": "JSON Number or JSON Null",
                            "mono": false
                        },
                        "example": {
                            "value": "null",
                            "mono": true
                        },
                        "source": {
                            "value": "/custom_units/list",
                            "mono": false,
                            "link": "/documentation/custom_unit_list"
                        }
                    },
                    {
                        "key": {
                            "value": "\"depth\"",
                            "mono": true
                        },
                        "description": {
                            "value": "The number of levels of Accounts you wish the Position to include. Specify null for full depth.",
                            "mono": false
                        },
                        "type": {
                            "value": "JSON Number or JSON Null",
                            "mono": false
                        },
                        "example": {
                            "value": "3",
                            "mono": true
                        },
                        "max value": {
                            "value": 4096,
                            "mono": true
                        },
                        "min value": {
                            "value": 1,
                            "mono": true
                        }
                    }
                ]
            },
            "required_headers": [
                {
                    "key": "X-Signature",
                    "content": "Your <a class=\"link\" href=\"/documentation/sessions\">Session</a> signature",
                    "example": "\"yxATCPRKAAXHNiPctNQPHEGGVJF\"..."
                },
                {
                    "key": "X-Session-ID",
                    "content": "An an integer <a class=\"link\" href=\"/documentation/sessions\">Session</a> ID",
                    "example": 7449059267091272858
                }
            ],
            "required_url_parameters": [
                {
                    "key": "entity_id",
                    "type": "string",
                    "description": "The entity id of the Entity for which you wish to retrieve a Performance",
                    "example": "oB3cjSNKXklkJ4Tb",
                    "repeatable": false
                }
            ],
            "returns": {
                "root": "object",
                "components": {
                    "object": "tree"
                }
            }
        }
    ]
}