Benchmark Calculator Public API
Important Notice
This documentation is in DRAFT state pending completion of architectural review and implementation phases of the BMC Public API MVP project. The APIs and message structures can change until execution phase of MVP is complete.
In addition, this documentation provides the full scope of capabilities of the public API. The actual features, parameters and attributes which are available to end users will be determined by their roles and permissions. Please contact BMC Product Support for more information.
API Conventions
- An endpoint represents a collecton of resources. We will always represent resources in plural form (e.g.
/reportsnot/report). - We will only support producing JSON output in the MVP implementation.
- We will default attribute naming convention to pascal case
- All responses will be compressed using gzip compression.
- Dates will be represented in the following format:
yyyy-mm-dd - Timestamps will be represented in UTC in the following format:
yyyy-mm-ddThh:MM:ss.SSSZ - The API will support Level 2 of the Richardson Maturity Model. Hypermedia will not be implemented without client feedback. YAGNI!
HTTP Status Codes and what they mean
| Http Status Code | Description |
|---|---|
| 202 | The request has been accepted and will be actioned based on the scheduled defined in the message structure |
| 400 | Your request was not valid |
| 401 | Unauthorized to access resource |
| 403 | The server understood your request, but refuses to statisfy it |
| 404 | The record requested does not exist or is not in your profile |
| 429 | You have been throttled! |
POST and PUT Requests Message Primitives
In ALL cases, the HTTP POST and PUT will always take the same basic form made up of two attributes: Parameters and Metadata.
Parameters is a JSON object which will provide specific information about the resource to be created. For example, when creating a report, it will contain information to identify the report, the specifics of the output and information about the scheduling.
Metadata is a JSON object which is reserved for the mechanics (usually internal) of a messaging interaction. For example, the BMC listener servers, when publishing a report, may pass tracer and debugging information into the API to get access to specific stats which help with debugging. Those attributes will always be published via Metadata.
{
"Parameters" : {},
"Metadata" : {}
}
HTTP Response Message Primitives
In ALL cases, the HTTP response will contain the following set of attributes: RequestId, StatusCode, Errors, Payload, and Stats.
RequestId is the system generated identifier for each request. All system interaction is logged and tagged at the per request level, using this system generated id StatusCode is the HTTP Status Code (also in the http headers). Errors is a one-to-many array of error objects representing any problem the system identified during processing a request. An error object will contain an identifier (e.g. attribute name) and the error message associated with the identifier. Payload is the business data returned in all responses. For client side simplicity, The decision to universally return an array, even when there is only one response is to simplify both the server and client interaction. Stats is a list of metrics related to the individual execution. Examples: paging statistics, the time it took to generate a benchmark report, debugging flags etc. are examples of Stats
Success Response
{
"RequestId" : "",
"StatusCode" : 200,
"Errors" : null,
"Payload" : [],
"Stats" : {}
}
Error Response
{
"RequestId" : "",
"StatusCode" : 400,
"Errors" : [],
"Payload" : null,
"Stats" : {}
}
| AttrName | DataType | Nullable | Default |
|---|---|---|---|
| RequestId | uuidv4 | false | sys generated |
| StatusCode | int | false | http status code |
| Errors | array | true | an array of objects. null if payload exists |
| Payload | object | true | the output of the report. null if errors exists |
| Stats | object | true | system generated stats about the request, to include paging, exec times etc. |
Endpoints MVP
Create a Scheduled Benchmark Report API
This endpoint allows users the create a new benchmark report which can be run on a scheduled basis.
Endpoint
POST /api/v1/reports
Request Body Example
{
"Parameters" : {
"BenchmarkId" : "ab79ec4c-d341-41a2-a104-9f7128639b72",
"ReportType" : "",
"ReportCurrency" : "USD",
"DataMode" : "2019Q2",
"Scheduling" : {
"IncludePrelim": true,
"Frequency" : "Daily"
},
"AttributeFilter" : [
"IRRPooled","IRREqualWeighted","IRRAverage","IRRMax",
"IRR95Percentile","IRRQuartileUpper",
"IRRQuartileLower", "IRR5Percentile","IRRMin"],
}
}
| AttrName | DataType | Nullable | Description |
|---|---|---|---|
| BenchmarkId | uuidv4 | false | this is the ID of the predefined BMC benchmark |
| ReportType | string | false | this is one of the report types allowed |
| ReportCurrency | string(3) | true | converts reports into a target currency. Defaults to USD |
| DataMode | string | true | See BMC product documentation on data mode. Defaults to current data mode. |
| Scheduling | object | false | Defines the scheduling model |
| Scheduling.IncludePrelim | boolean | false | Defines whether prelim data is acceptable in the calculations |
| Scheduling.Frequency | string | false | Must be "Current" which tells the api to queue the report to execute asap (async) , "Daily" which will run the report every day during daily batch process, "Quarterly" which will run the report on the first day following a quarter end |
| AttributeFilter | array of strings | true | allows you to only return a subset of attributes you care about. The default is to return ALL attributes. Note some attributes (such as BenchmarkId cannot be filtered out of the result) |
A note about AttributeFilter, a user may have restrictions on the collection of attributes which they can access. If you select an attribute to be returned which is not in your profile, you will receive a 400 Bad Request error with the attributes you cannot select highlighted.
Report Types and Available Parameters
There are total of five distinct report types supported by the Public API with a distinct set of parameters
- Default mPME Index (DEFAULT_MPME_INDEX)
- Since Inception (SINCE_INCEPTION)
- Since Inception mPME (SINCE_INCEPTION_MPME)
- Horizon (HORIZON)
- Horizon mPME (HORIZON_MPME)
| Benchmark Name | Report Type | Parameter | Data Type | Optional | Default | Notes |
|---|---|---|---|---|---|---|
| Default mPME Index | DEFAULT_MPME_INDEX | |||||
| Since Inception | SINCE_INCEPTION | BenchmarkId | uuidv4 | false | ||
| Since Inception | SINCE_INCEPTION | AsOfDate | date | true | yyyy-mm-dd | |
| Since Inception | SINCE_INCEPTION | Currency | string | true | USD | ISO Curr |
| Since Inception | SINCE_INCEPTION | DataMode | string | true | yyyyQ# | |
| Since Inception | SINCE_INCEPTION | Universe | string | true | CA Benchmark | enumerated |
| Since Inception | SINCE_INCEPTION | ReportedBy | number | true | ||
| Since Inception | SINCE_INCEPTION | Internal | boolean | true | false | |
| Since Inception mPME | SINCE_INCEPTION_MPME | BenchmarkId | uuidv4 | false | ||
| Since Inception mPME | SINCE_INCEPTION_MPME | AsOfDate | date | true | yyyy-mm-dd | |
| Since Inception mPME | SINCE_INCEPTION_MPME | Currency | string | true | USD | ISO Curr |
| Since Inception mPME | SINCE_INCEPTION_MPME | DataMode | string | true | yyyyQ# | |
| Since Inception mPME | SINCE_INCEPTION_MPME | Universe | string | true | CA Benchmark | enumerated |
| Since Inception mPME | SINCE_INCEPTION_MPME | ReportedBy | number | true | ||
| Since Inception mPME | SINCE_INCEPTION_MPME | Index | number | true | enumerated | |
| Since Inception mPME | SINCE_INCEPTION_MPME | Internal | boolean | true | false | |
| Horizon | HORIZON | BenchmarkId | uuidv4 | false | ||
| Horizon | HORIZON | StartDate | date | true | yyyy-mm-dd | |
| Horizon | HORIZON | EndDate | date | true | yyyy-mm-dd | |
| Horizon | HORIZON | Currency | string | true | USD | ISO Curr |
| Horizon | HORIZON | DataMode | string | true | yyyyQ# | |
| Horizon | HORIZON | Universe | string | true | CA Benchmark | Enumerated |
| Horizon | HORIZON | ReportedBy | number | true | ||
| Horizon | HORIZON | Internal | boolean | true | false | |
| Horizon mPME | HORIZON_MPME | BenchmarkId | uuidv4 | false | ||
| Horizon mPME | HORIZON_MPME | StartDate | date | true | yyyy-mm-dd | |
| Horizon mPME | HORIZON_MPME | EndDate | date | true | yyyy-mm-dd | |
| Horizon mPME | HORIZON_MPME | Currency | string | true | USD | ISO Curr |
| Horizon mPME | HORIZON_MPME | DataMode | string | true | yyyyQ# | |
| Horizon mPME | HORIZON_MPME | Universe | string | true | CA Benchmark | enumerated |
| Horizon mPME | HORIZON_MPME | Index | string | true | enumerated | |
| Horizon mPME | HORIZON_MPME | Internal | boolean | true | false |
Success Response Example
A successful execution will respond with an HTTP 202 and will echo the parameters with the API generated ReportId
{
"RequestId" : "692ddba1-1cd6-44df-8b32-be4fd6e89d8b",
"StatusCode" : 202,
"Errors" : null,
"Payload" : [
{
"ReportId" : "0fe4dc19-71ae-48f2-8f1f-f3e20ffd8959",
"ReportCurrency" : "USD",
"DataMode" : "2019Q2",
"Scheduling" : {
"IncludePrelim": true,
"Frequency" : "Daily"
},
"AttributeFilter" : [
"IRRPooled","IRREqualWeighted","IRRAverage","IRRMax",
"IRR95Percentile","IRRQuartileUpper",
"IRRQuartileLower", "IRR5Percentile","IRRMin"],
"CreatedOn" : "2020-06-25T13:21:51.000Z",
"CreatedBy" : "jdoe",
"LastModOn" : "2020-06-25T13:21:51.000Z",
"LastModBy" : "tsmith"
}
],
"Stats" : {}
}
Failure Response Examples
Ex. an attribute in the Parameters object is not a valid format
{
"RequestId" : "692ddba1-1cd6-44df-8b32-be4fd6e89d8b",
"StatusCode" : 400,
"Errors" : [
{
"Id" : "ReportCurrency",
"Message": "ReportCurrency must be a valid ISO Currency"
}
],
"Payload" : null,
"Stats": {}
}
Ex. the request message doesnt contain a Parameters attribute
{
"RequestId" : "692ddba1-1cd6-44df-8b32-be4fd6e89d8b",
"StatusCode" : 400,
"Errors" : [
{
"Id" : "Envelope",
"Message": "Parameters is a required top-level attribute" }
],
"Payload" : null,
"Stats": {}
}
Get Scheduled Benchmark Report API
Provides a user with the configuration for a previously saved report.
Endpoint
GET /api/v1/reports/{reportId}
Success Response Example
{
"RequestId" : "692ddba1-1cd6-44df-8b32-be4fd6e89d8b",
"StatusCode" : 202,
"Errors" : null,
"Payload" : [
{
"ReportId" : "0fe4dc19-71ae-48f2-8f1f-f3e20ffd8959",
"ReportCurrency" : "USD",
"DataMode" : "2019Q2",
"Scheduling" : {
"IncludePrelim": true,
"Frequency" : "Daily"
},
"AttributeFilter" : [
"IRRPooled","IRREqualWeighted","IRRAverage","IRRMax",
"IRR95Percentile","IRRQuartileUpper",
"IRRQuartileLower", "IRR5Percentile","IRRMin"],
"CreatedOn" : "2020-06-25T13:21:51.000Z",
"CreatedBy" : "jdoe",
"LastModOn" : "2020-06-25T13:21:51.000Z",
"LastModBy" : "tsmith"
}
],
"Stats" : {
"LastExec" : "2020-08-10"
}
Get Report Execution API
This API execution will retrieve a report that has been run by the system.
Endpoint
GET /api/v1/reports/{reportId}/{date}
Response Body Example If the report has been run, the response will be as follows:
{
"RequestId" : "692ddba1-1cd6-44df-8b32-be4fd6e89d8b",
"StatusCode" : 200,
"Errors" : null,
"Payload" : [
{
"BenchmarkId" : "ab79ec4c-d341-41a2-a104-9f7128639b72",
"RunStatus" : "COMPLETE",
"AsOfDate" : "2020-08-10",
"ReportCurrency" : "USD",
"DataMode" : "2020Q2",
"IRRPooled": 10.75,
"IRREqualWeighted": 15.31,
"IRRAverage": 10.99,
"IRRMax": null,
"IRR95Percentile": 28.52,
"IRRQuartileUpper": 13.90,
"IRRQuartileLower": 6.17,
"Irr5Percentile": -0.39,
"IRRMin": null
}
],
"Stats" : {
"FundCount" : 241,
"ExecStartTime" : "2020-08-10T15:31:25.352Z",
"ExecEndTime" : "2020-08-10T15:42:03.812Z"
}
}
Report Attributes Based on Report Type
| Report Type | Attribute Name | Data Type | Notes |
|---|---|---|---|
| SINCE_INCEPTION | BenchmarkId | uuidv4 | |
| SINCE_INCEPTION | VintageYear | Number | |
| SINCE_INCEPTION | FirstTransaction | date | yyyy-mm-dd |
| SINCE_INCEPTION | AsOfDate | date | yyyy-mm-dd |
| SINCE_INCEPTION | FundCount | number | |
| SINCE_INCEPTION | IRRPooled | number | |
| SINCE_INCEPTION | IRREqualWeighted | number | |
| SINCE_INCEPTION | IRREqualWeighted | number | |
| SINCE_INCEPTION | CapitalWeightedSILPIRR | number | |
| SINCE_INCEPTION | IRRAverage | number | |
| SINCE_INCEPTION | IRRMax | number | |
| SINCE_INCEPTION | IRR95Percentile | number | |
| SINCE_INCEPTION | IRRQuartileUpper | number | |
| SINCE_INCEPTION | IRRMedian | number | |
| SINCE_INCEPTION | IRRQuartileLower | number | |
| SINCE_INCEPTION | IRR5Percentile | number | |
| SINCE_INCEPTION | IRRMin | number | |
| SINCE_INCEPTION | StandardDeviation | number | |
| SINCE_INCEPTION | TVPIPooledLP | number | |
| SINCE_INCEPTION | TVPICapitalWeightedLP | number | |
| SINCE_INCEPTION | TVPIAverageLPTVPIMaxLP | number | |
| SINCE_INCEPTION | TVPI95Percentile | number | |
| SINCE_INCEPTION | TVPIQuartileUpperLP | number | |
| SINCE_INCEPTION | TVPIMedianLP | number | |
| SINCE_INCEPTION | TVPIQuartileLowerLP | number | |
| SINCE_INCEPTION | TVPI5Percentile | number | |
| SINCE_INCEPTION | TVPIMinLP | number | |
| SINCE_INCEPTION | TVPIStandardDeviationLP | number | |
| SINCE_INCEPTION | DPIPooledLP | number | |
| SINCE_INCEPTION | DPICapitalWeightedLP | number | |
| SINCE_INCEPTION | DPIAverageLP | number | |
| SINCE_INCEPTION | DPIMaxLP | number | |
| SINCE_INCEPTION | Dpi95Percentile | number | |
| SINCE_INCEPTION | DPIQuartileUpperLP | number | |
| SINCE_INCEPTION | DPIMedianLP | number | |
| SINCE_INCEPTION | BenchmarkId | uuidv4 | |
| SINCE_INCEPTION_MPME | IndexId | string | enumerated |
| SINCE_INCEPTION_MPME | FundCount | number | |
| SINCE_INCEPTION_MPME | IRRPooled | number | |
| SINCE_INCEPTION_MPME | ValueAdded | number | |
| SINCE_INCEPTION_MPME | ValueAddedLP | number | |
| SINCE_INCEPTION_MPME | TVPIPooledLP | number | |
| SINCE_INCEPTION_MPME | DPIPooledLP | number | |
| SINCE_INCEPTION_MPME | LPNavBeginning | number | |
| SINCE_INCEPTION_MPME | LPContribution | number | |
| SINCE_INCEPTION_MPME | LPNavBeginning | number | |
| SINCE_INCEPTION_MPME | LPContribution | number | |
| SINCE_INCEPTION_MPME | LPDistribution | number | |
| SINCE_INCEPTION_MPME | LPNav | number | |
| HORIZON | BenchmarkId | uuidv4 | |
| HORIZON | FirstTransaction | string | yyyy Q# |
| HORIZON | Calculation | string | ex.1-Quarter IRR |
| HORIZON | StartDate | date | yyyy-mm-dd |
| HORIZON | EndDate | date | yyyy-mm-dd |
| HORIZON | FundCount | number | |
| HORIZON | TotalCapitalization | number | |
| HORIZON | CapitalizationGP | number | |
| HORIZON | CapitalizationLP | number | |
| HORIZON | IRRPooled | number | |
| HORIZON | IRREqualWeighted | number | |
| HORIZON | IRRAverage | number | |
| HORIZON | IRRMax | number | |
| HORIZON | IRR95Percentile | number | |
| HORIZON | IRRQuartilePercentile | number | |
| HORIZON | IRRMedian | number | |
| HORIZON | IRRQuartileLower | number | |
| HORIZON | IRR5Percentile | number | |
| HORIZON | IRRMin | number | |
| HORIZON | StandardDeviation | number | |
| HORIZON_MPME | BenchmarkId | uuidv4 | |
| HORIZON_MPME | Calculation | string | ex.1-Quarter IRR |
| HORIZON_MPME | IndexId | string | enumerated |
| HORIZON_MPME | StartDate | date | yyyy-mm-dd |
| HORIZON_MPME | EndDate | date | yyyy-mm-dd |
| HORIZON_MPME | FundCount | number | |
| HORIZON_MPME | IRRPooled | number | |
| HORIZON_MPME | ValueAdded | number | |
| HORIZON_MPME | LPNavBeginning | number | |
| HORIZON_MPME | LPContribution | number | |
| HORIZON_MPME | LPDistribution | number | |
| HORIZON_MPME | LPNav | number | |
| INVESTMENT_LEVEL | BenchmarkId |
TODO: Document Investment Level Attributes
Reference Data APIs
This set of calls provides access to the enumerations within the system.
Get Benchmarks
Returns the list of Benchmarks
Endpoint
GET /api/v1/benchmarks
Request Body
None
Response Body Example
{
"RequestId" : "692ddba1-1cd6-44df-8b32-be4fd6e89d8b",
"StatusCode" : 200,
"Errors" : null,
"Payload" : [
{
"BenchmarkId" : "1c84e8a9-d9e6-4a64-ab01-6cbee2621783",
"BenchmarkName" : "Distressed Securities"
},
{
"BenchmarkId" : "e83ed52f-8d67-4273-85d7-192036174c0d",
"BenchmarkName" : "Distressed Securities"
},
// ....
]
},
"Stats" : {}
}