user

Bullsfirst REST API

Introduction

user

Naresh Bhatia

Naresh is a software architect in the Boston area. He started Archfirst after realizing that technologists spend too much time fighting technologies instead of solving real-world problems. Archfirst is a place where we can all learn best practices and techniques to make software development easier.


LATEST POSTS

JoinJS – An Alternative to Complex ORMs 10th August, 2015

MyBatis vs. Other ORMs 01st July, 2015

Bullsfirst REST API

Posted on .

Bullsfirst provides a RESTful API to facilitate securities trading. The implementation conforms to REST Maturity Level 2. The API exposes the following resources:

General Concepts

Following the REST architecture guidelines, we expose Bullsfirst functions as a set of resources that can be manipulated using HTTP verbs. POST is used to create resources and GET is used to get them. The sections below describe the general patterns we follow.

Create Resource

Request

POST /{resource-collection} HTTP/1.1
Content-Type: application/json

{ creation parameters }

Response – Success

HTTP/1.1 201 Created
Location: /{resource-collection}/{resource-id}
Content-Type: application/json

{
    "rel": "self",
    "id": "id of the newly created resource",
    "uri": "uri of the newly created resource"
}

Response – Failure

HTTP/1.1 409 Conflict

{ "detail": "Detailed error description" }

Get Resource

Request

GET /{resource-collection}/{resource-id} HTTP/1.1

Response – Success

HTTP/1.1 200 OK
Content-Type: application/json

{ resource }

Response – Failure (Unauthorized)

HTTP/1.1 401 Unauthorized

Response – Failure (NotFound)

HTTP/1.1 404 NotFound

Other Use Cases

POST /{resource-collection}/{resource-id}/{usecase} HTTP/1.1
Content-Type: application/json

{ usecase parameters }

Response – Success

HTTP/1.1 200 OK
Content-Type: application/json

optional result formatted as json

Response – Failure

HTTP/1.1 409 Conflict (409 used as an example error code)

{ "detail": "Detailed error description" }

Security

This API uses both unsecure and secure requests. Unsecured requests are sent to the URL http://apps.archfirst.org/bfoms-javaee/rest, whereas secured requests are sent to the URL http://apps.archfirst.org/bfoms-javaee/rest/secure. We use HTTP Basic Authentication for secure requests. For such requests, their descriptions below include the Authorization header. If authentication fails, the API will return error code 401 (Unauthorized) as shown below. For the sake of brevity, we will not repeat this failure response in request descriptions.

HTTP/1.1 401 Unauthorized

There is one secure request that does not use Basic Authentication – it’s the GET User request. Using Basic Authentication causes an ugly auth dialog to pop up when the user types in invalid credentials (the browser does this when it receives a WWW-Authenticate header from the server – there doesn’t seem to be any way around this). To avoid this we use a simple password header for GET User instead of the standard Authorization header and then doing custom authentication inside the server code.

Users

Create User

Request

POST http://apps.archfirst.org/bfoms-javaee/rest/users HTTP/1.1
Content-Type: application/json

{
    "firstName": "John",
    "lastName": "Adams",
    "username": "jadams",
    "password": "smart"
}

Response – Success

HTTP/1.1 201 Created
Location: http://apps.archfirst.org/bfoms-javaee/rest/users/jadams
Content-Type: application/json

{
    "rel": "self",
    "id": "jadams",
    "uri": "http://apps.archfirst.org/bfoms-javaee/rest/users/jadams"
}

Response – Failure

HTTP/1.1 409 Conflict

{
    "detail": "Username already exists"
}

Get User

This request is used by front-end clients to login to Bullsfirst. Note that there is no concept of user sessions in the stateless REST architecture. In that vein, this is a stateless request which is used simply to authenticate the user and capture their credentials for subsequent requests.

Request

GET http://apps.archfirst.org/bfoms-javaee/rest/users/jadams HTTP/1.1
password: smart

Response – Success

HTTP/1.1 200 OK
Content-Type: application/json

{
    "username": "jadams",
    "firstName": "John",
    "lastName": "Adams"
}

Response – Failure (Unauthorized)

HTTP/1.1 401 Unauthorized

Accounts

Change Account Name

Request

POST http://apps.archfirst.org/bfoms-javaee/rest/secure/accounts/1234/change_name HTTP/1.1
Content-Type: application/json
Authorization: Basic amFkYW1zOnNtYXJ0

{
    "newName": "Brokerage Account 2"
}

Response

HTTP/1.1 200 OK

Transfer Cash

Request

POST http://apps.archfirst.org/bfoms-javaee/rest/secure/accounts/1234/transfer_cash HTTP/1.1
Content-Type: application/json
Authorization: Basic amFkYW1zOnNtYXJ0

{
    "amount": {
      "amount": 1000.00,
      "currency": "USD"
    },
    "toAccountId": 5678
}

Response – Success

HTTP/1.1 200 OK

Response – Failure

HTTP/1.1 400 Bad Request

{
    "detail": "Detailed Reason"
}

Transfer Securities

Request

POST http://apps.archfirst.org/bfoms-javaee/rest/secure/accounts/1234/transfer_securities HTTP/1.1
Content-Type: application/json
Authorization: Basic amFkYW1zOnNtYXJ0

{
    "symbol": "CSCO",
    "quantity": 1000,
    "pricePaidPerShare": {
      "amount": 19.23,
      "currency": "USD"
    },
    "toAccountId": 5678
}

Response – Success

HTTP/1.1 200 OK

Response – Failure

HTTP/1.1 400 Bad Request

{
    "detail": "Detailed Reason"
}

Brokerage Accounts

Create Brokerage Account

Creates a brokerage account for the authenticated user.

Request

POST http://apps.archfirst.org/bfoms-javaee/rest/secure/brokerage_accounts HTTP/1.1
Content-Type: application/json
Authorization: Basic amFkYW1zOnNtYXJ0

{
    "accountName": "Brokerage Account 1"
}

Response

HTTP/1.1 201 Created
Location: http://apps.archfirst.org/bfoms-javaee/rest/secure/brokerage_accounts/1234
Content-Type: application/json

{
    "rel": "self",
    "id": "1234",
    "uri": "http://apps.archfirst.org/bfoms-javaee/rest/secure/brokerage_accounts/1234"
}

Get Brokerage Accounts

Returns summary information about all brokerage accounts for which the requesting user has View permissions. Each summary object is a hierarchical object consisting of some general information along with a combination of instrument and cash positions (see diagram below). Instrument positions are further broken down to lot positions. For example, an account can have a 1000 shares of AAPL (instrument position) which come from two lots of 500 shares each (lot positions).

Brokerage Account Summary

Request

GET http://apps.archfirst.org/bfoms-javaee/rest/secure/brokerage_accounts HTTP/1.1
Authorization: Basic amFkYW1zOnNtYXJ0

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 1,
    "name": "Brokerage Account 1",
    "marketValue": {
      "amount": 3000,
      "currency": "USD"
    },
    "cashPosition": {
      "amount": 1000,
      "currency": "USD"
    },
    "editPermission": true,
    "tradePermission": true,
    "transferPermission": true,
    "positions": [
      {
        "accountId": 1,
        "accountName": "Brokerage Account 1",
        "instrumentSymbol": "CASH",
        "instrumentName": "Cash",
        "marketValue": {
          "amount": 1000,
          "currency": "USD"
        }
      },
      {
        "accountId": 1,
        "accountName": "Brokerage Account 1",
        "instrumentSymbol": "CSCO",
        "instrumentName": "CSCO",
        "quantity": 100,
        "marketValue": {
          "amount": 2000,
          "currency": "USD"
        },
        "lastTrade": {
          "amount": 20,
          "currency": "USD"
        },
        "pricePaid": {
          "amount": 10,
          "currency": "USD"
        },
        "totalCost": {
          "amount": 1000,
          "currency": "USD"
        },
        "gain": {
          "amount": 1000,
          "currency": "USD"
        },
        "gainPercent": 1,
        "children": [
          {
            "accountId": 1,
            "accountName": "Brokerage Account 1",
            "instrumentSymbol": "CSCO",
            "instrumentName": "CSCO",
            "lotId": 1,
            "lotCreationTime": "2011-01-01T00:00:00.000-05:00",
            "quantity": 100,
            "marketValue": {
              "amount": 2000,
              "currency": "USD"
            },
            "lastTrade": {
              "amount": 20,
              "currency": "USD"
            },
            "pricePaid": {
              "amount": 10,
              "currency": "USD"
            },
            "totalCost": {
              "amount": 1000,
              "currency": "USD"
            },
            "gain": {
              "amount": 1000,
              "currency": "USD"
            },
            "gainPercent": 1
          }
        ]
      }
    ]
  }
]

External Accounts

Create External Account

Creates an external account for the authenticated user.

Request

POST http://apps.archfirst.org/bfoms-javaee/rest/secure/external_accounts HTTP/1.1
Content-Type: application/json
Authorization: Basic amFkYW1zOnNtYXJ0

{
    "name": "External Account 1",
    "routingNumber": 022000248,
    "accountNumber": 12345678
}

Response

HTTP/1.1 201 Created
Location: http://apps.archfirst.org/bfoms-javaee/rest/secure/external_accounts/1234
Content-Type: application/json

{
    "rel": "self",
    "id": "1234",
    "uri": "http://apps.archfirst.org/bfoms-javaee/rest/secure/external_accounts/1234"
}

Get External Accounts

Returns summary information about all external accounts for which the requesting user has access permissions.

Request

GET http://apps.archfirst.org/bfoms-javaee/rest/secure/external_accounts HTTP/1.1
Authorization: Basic amFkYW1zOnNtYXJ0

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 1234,
    "name": "External Account 1",
    "routingNumber": 022000248,
    "accountNumber": 12345678
  },
  {
    "id": 1299,
    "name": "External Account 2",
    "routingNumber": 022000248,
    "accountNumber": 12345679
  }
]

Order Estimates

Create Order Estimate

Creates an order estimate for placing an order in the specified account. This call performs several compliance checks to make sure that the order is indeed “placeable”. For example, it checks that the account holds enough quanity of the security for a sell order or enough cash for a buy order. If the compliance checks succeed, it returns the estimated total for the order including fees. This call is usually made for “previewing” an order before actually placing it.

Request

POST http://apps.archfirst.org/bfoms-javaee/rest/secure/order_estimates HTTP/1.1
Content-Type: application/json
Authorization: Basic amFkYW1zOnNtYXJ0

{
    "brokerageAccountId": 1234,
    "orderParams": {
        "side": "Buy",
        "symbol": "AAPL",
        "quantity": 10,
        "type": "Limit",
        "limitPrice": {
            "amount": 344.00,
            "currency": "USD"
        },
        "term": "GoodForTheDay",
        "allOrNone": false
    }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "compliance: "Compliant",
    "estimatedValue": {
        "amount": 3440.00,
        "currency": "USD"
    },
    "fees": {
        "amount": 10.00,
        "currency": "USD"
    },
    "estimatedValueInclFees": {
        "amount": 3450.00,
        "currency": "USD"
    }
}

Orders

Create Order

Creates an order in a brokerage account.

Request

POST http://apps.archfirst.org/bfoms-javaee/rest/secure/orders HTTP/1.1
Content-Type: application/json
Authorization: Basic amFkYW1zOnNtYXJ0

{
    "brokerageAccountId": 1234,
    "orderParams": {
        "side": "Sell",
        "symbol": "AAPL",
        "quantity": 100,
        "type": "Limit",
        "limitPrice": {
            "amount": 344.60,
            "currency": "USD"
        },
        "term": "GoodForTheDay",
        "allOrNone": false
    }
}

Response – Success

HTTP/1.1 201 Created
Location: http://apps.archfirst.org/bfoms-javaee/rest/secure/orders/1234
Content-Type: application/json

{
    "rel": "self",
    "id": "1234",
    "uri": "http://apps.archfirst.org/bfoms-javaee/rest/secure/orders/1234"
}

Response – Failure

HTTP/1.1 400 Bad Request

{
    "detail": "Detailed Reason"
}

Cancel Order

Request

POST http://apps.archfirst.org/bfoms-javaee/rest/secure/orders/1234/cancel HTTP/1.1
Content-Type: application/json
Authorization: Basic amFkYW1zOnNtYXJ0

Response – Success

HTTP/1.1 200 OK

Response – Failure

HTTP/1.1 400 Bad Request

{
    "detail": "Detailed Reason"
}

Get Orders

Returns orders matching zero or more of the following criteria. Each criterion is defined as a query parameter. If a criterion is not specified, the result is not constrained by that criterion. Order executions are sent as child elements of orders.

  • accountId: Matches orders for the specified account. (If not specified, matches all accounts with view permissions.)
  • symbol: Matches orders for the specified symbol.
  • orderId: Matches a single order with the specified id.
  • fromDate: Matches orders on or after the specified date.
  • toDate: Matches orders on or before the specified date.
  • sides: Matches orders with a comma seperated list of sides. Valid values: Buy, Sell
  • statuses: Matches orders with a comma seperated list of statuses. Valid values: PendingNew, New, PartiallyFilled, Filled, PendingCancel, Canceled, DoneForDay

Request

The following example shows all orders placed on or after 1/1/2011 with a status of Filled or Canceled.

GET http://apps.archfirst.org/bfoms-javaee/rest/secure/orders?fromDate=2011-01-01&statuses=Filled,Canceled HTTP/1.1
Authorization: Basic amFkYW1zOnNtYXJ0

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 30,
    "creationTime": "2011-04-22T00:34:54.000-04:00",
    "side": "Buy",
    "symbol": "CSCO",
    "quantity": 100,
    "cumQty": 100,
    "type": "Market",
    "term": "GoodForTheDay",
    "allOrNone": false,
    "status": "Filled",
    "accountId" : 1234,
    "accountName" : "Brokerage Account 1",
    "executions": [
      {
        "id": 35,
        "creationTime": "2011-04-22T00:34:54.000-04:00",
        "quantity": 70,
        "price": {
          "amount": 17.5000,
          "currency": "USD"
        }
      },
      {
        "id": 39,
        "creationTime": "2011-04-22T07:43:20.000-04:00",
        "quantity": 30,
        "price": {
          "amount": 17.5000,
          "currency": "USD"
        }
      }
    ]
  },
  {
    "id": 36,
    "creationTime": "2011-04-24T09:08:06.000-04:00",
    "side": "Sell",
    "symbol": "AAPL",
    "quantity": 10,
    "cumQty": 0,
    "type": "Limit",
    "limitPrice": {
      "amount": 344.600,
      "currency": "USD"
    }
    "term": "GoodForTheDay",
    "allOrNone": false,
    "status": "Canceled",
    "accountId" : 1234,
    "accountName" : "Brokerage Account 1"
  }
]

Transactions

Get Transactions

Returns transaction summaries matching zero or more of the following criteria. Each criterion is defined as a query parameter. If a criterion is not specified, the result is not constrained by that criterion.

  • accountId: Matches transactions for the specified account. (If not specified, matches all accounts with view permissions.)
  • fromDate: Matches transactions on or after the specified date.
  • toDate: Matches transactions on or before the specified date.

Request

The following example shows all transactions executed in 2011.

GET http://apps.archfirst.org/bfoms-javaee/rest/secure/tansactions?fromDate=2011-01-01&toDate=2011-12-31 HTTP/1.1
Authorization: Basic amFkYW1zOnNtYXJ0

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "accountId": 1,
    "accountName" : "Brokerage Account 1",
    "transactionId": 2,
    "creationTime": "2011-04-22T00:34:54.000-04:00",
    "type": "Transfer",
    "description": "Transfer cash from External Account 1",
    "amount": {
        "amount": 100000.00,
        "currency": "USD"
    }
  },
  {
    "accountId": 1,
    "accountName" : "Brokerage Account 1",
    "transactionId": 10,
    "creationTime": "2011-05-15T00:42:24.000-04:00",
    "type": "Trade",
    "description": "Sold 10 shares of AAPL @ $340.0000",
    "amount": {
        "amount": 3390.00,
        "currency": "USD"
    }
  }
]

Instruments

Note that instrument information is served from the exchange (http://apps.archfirst.org/bfexch-javaee/).

Get Instruments

Returns all Instruments traded at the exchange. This call is intended to be made by the front-end
very infrequently (perhaps during startup or user login) to cache all the instrument data.

Request

GET http://apps.archfirst.org/bfexch-javaee/rest/instruments HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "symbol": "A",
    "name": "Agilent Technologies Inc.",
    "exchange": "NYSE"
  },
  {
    "symbol": "AA",
    "name": "Alcoa Inc.",
    "exchange": "NYSE"
  },
  ...
]

Get Instrument

Returns the Instrument for the given symbol.

Request

GET http://apps.archfirst.org/bfexch-javaee/rest/instruments/CSCO HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "symbol": "CSCO",
  "name": "Cisco Systems Inc.",
  "exchange": "NYSE"
}

Market Prices

Note that market prices are served from the exchange (http://apps.archfirst.org/bfexch-javaee/).

Get Market Price

Returns the MarketPrice for the given symbol.

Request

GET http://apps.archfirst.org/bfexch-javaee/rest/market_prices/AAPL HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "symbol": "AAPL",
  "price": {
    "amount": 348.1600,
    "currency": "USD"
  },
  "effective": "2011-02-25T16:00:00.000-05:00"
}
profile

Naresh Bhatia

Naresh is a software architect in the Boston area. He started Archfirst after realizing that technologists spend too much time fighting technologies instead of solving real-world problems. Archfirst is a place where we can all learn best practices and techniques to make software development easier.

There are no comments.

Leave a Reply

View Comments (0) ...
Navigation