Margin Service API - Use Cases

Use Case 1. Creating a New Portfolio

Margin Service API Flow

Requests

Description

Create Portfolio

Client submits required attributes for a portfolio
Server validates request, including checks for uniqueness (name is unique)
If the request is valid, an internal identifier and status are returned
If the request is invalid, a status and error message/error code are returned
Does not include transactions (trades)

Alter Transactions

Allows transactions to be uploaded in bulk (multiple transactions in a single request)
Supports a "mixed mode" allowing transactions to be created, updated, and deleted
A valid portfolio identifier must be specified
All transactions must be in a single portfolio
Transactions being created must be specified with all the required attributes.
Transactions being updated must have the attributes being updated and the system internal identifier
Transactions being deleted must have the internal identifier of the transaction
The sever will return a request identifier

Workflow

Use Case 2. Calculating Margin on an Existing Portfolio

Margin Service API Flow

Requests

Description

Calculate Margin

Client submits margin type (full, incremental)
Client must submit portfolio identifier
Client may submit additional (transient) transactions by value
Client may submit transactions to exclude by identifier from the portfolio
Client may submit additional portfolio by reference
Client may submit transaction IDs by reference (allowed for their user)
The server will queue up the request for execution
If the portfolio does not exist, referenced transactions do not exist, or there are other errors an error message/code will be returned
If the request is valid, then after the request is submitted to the risk engine for processing a request identifier and status are returned.

Get Calculate Margin Result

Client submits margin request identifier
Server returns the identifier, status, error (if applicable), and result (if available)

Workflow

Use Case 3. Calculating Margin on an Existing Portfolio with Additions/Subtractions

Margin Service API Flow

Requests	Description
Alter Transactions	Allows transactions to be uploaded in bulk (multiple transactions in a single request) Supports a "mixed mode" allowing transactions to be created, updated, and deleted A valid portfolio identifier must be specified All transactions must be in a single portfolio Transactions being created must be specified with all the required attributes Transactions being updated must have the attributes being updated and the system internal identifier Transactions being deleted must have the internal identifier of the transaction The sever will return a request identifier
Calculate Margin	Client submits margin type (full, incremental) Client must submit portfolio identifier Client may submit additional (transient) transactions by value Client may submit transactions to exclude by identifier from the portfolio Client may submit additional portfolio by reference Client may submit transaction IDs by reference (allowed for their user) The server will queue up the request for execution If the portfolio does not exist, referenced transactions do not exist, or there are other errors an error message/code will be returned If the request is valid, then after the request is submitted to the risk engine for processing a request identifier and status are returned
Get Alter Transactions Result	The client submits an identifier from the alter transactions request The server returns the overall status of the request, and results for all transactions if all have completed processing. The server will return an identifier (if available), status, and error message/error code (if applicable)
Get Calculate Margin Result	Client submits margin request identifier Server returns the identifier, status, error (if applicable), and result (if available)

Workflow

Use Case 4. List All Margin Results for a Portfolio

Margin Service API Flow

Requests	Description
List Margins	Client submits query criteria (portfolio ID, time range, etc.) Server returns identifier, status, error (if applicable), and result (if available) for all matching requests This is similar to the functionality in the MHQ Grid in the UI

Workflow

Use Case 5. List All Portfolios

Margin Service API Flow

Requests	Description
List Portfolios	Client can optionally submit search parameters (TBD) The server returns all portfolios matching the criteria Does not include transactions or other data Since this is querying local data, it is assumed that this can be returned synchronously

Workflow

Use Case 6. Update an Existing Portfolio

Margin Service API Flow

Requests	Description
Update Portfolio	Client submits an internal portfolio identifier and updated attributes If no portfolio is found with the identifier an error is returned If the user is not authorized to modify the portfolio an error is returned If the request is valid and successful, the internal identifier and status are returned Transactions must be submitted separately

Workflow

Use Case 7. Delete an Existing Portfolio

Margin Service API Flow

Requests	Description
Delete Portfolio	Client submits an internal portfolio identifier If no portfolio is found with the identifier, an error is returned If the user is not authorized to delete the portfolio, an error is returned The server will delete the portfolio and all associated data (transactions, margins, etc.). This is known as a "cascading delete"

Workflow

Use Case 8. List Transactions

Margin Service API Flow

Requests	Description
List Transaction	Client can optionally submit search criteria The server returns all portfolios matching the criteria Does not include transactions or other data The results of this request are returned synchronously

Workflow

Use Case 9. Get Transactions

Margin Service API Flow

Requests	Description
Get Transaction	Client submits an internal transaction identifier If no transaction is found with the identifier, an error is returned If the user is not authorized to get the transaction, an error is returned If the transaction is found it is returned

Workflow

Use Case 10. Calculating Optimize on an Existing Portfolio

Margin Service API Flow

Requests	Description
Calculate Optimize	Client must submit portfolio identifier The server will queue up the request for execution If the portfolio does not exist, referenced transactions do not exist, or there are other errors an error message/code will be returned If the request is valid, then after the request is submitted to the risk engine for processing a request identifier and status are returned.
Get Optimize Margin Result	Client submits Optimize request identifier Server returns the identifier, status, error (if applicable), and result (if available)