Hello and Welcome!

Within these pages you'll find all matter of resources for building custom applications with our easy-to-use web API. The City API has two primary objectives:

  • Make trading application development easy and efficient
  • Do so without sacrificing power and flexibility

We achieve these goals by using familiar web technologies and conventions, and carefully crafting around common trading concepts. If you have any questions, please contact us.


Web-based API — A Quick Introduction

If you're familiar with REST APIs, you can probably skip ahead. If not, please read on.

City API is web-based in that it uses many of the same technologies underlying the web, like HTTP, TCP and SSL. This means that using our API is as simple as a web browser's task of loading internet resources. For example, a command line utility called cURL on a Mac or Linux can be used to request web resources with the following simple command:

$ curl http://api.optionscity.com/marketdata/sample

You should get something like this:

{
  "instrument_id" : 1,
  "price" : 6.25,
  "quantity" : 5,
  "side" : "Last"
}

This is a JSON representation of some made-up option's market data. Part of the beauty of this approach is that you can easily interact with City API's scalable cloud services. There is no need to install and maintain any server software of your own!


Endpoint

All City API endpoints can be reached at the the following URL: https://api.optionscity.com


Authentication

Most requests made against City API must identify the user issuing the request. For this purpose, the API uses a protocol called OAuth 2.0 for authentication. This allows all requests to safely and securely identify both the user and client application. Please see City API documentation for requesting and refreshing OAuth tokens.

The basic idea is that to obtain a token, you will first use HTTP basic authentication with your OAuth client ID and secret. You must base-64 encode the string literal {OAuth client ID}:{OAuth client secret} and submit an HTTP authorization header like this:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Once a token is obtained, access to all secured resources should include the OAuth token in the Authorization header. Here's an example:

GET /products HTTP/1.1
Host: api.optionscity.com
Authorization: Bearer 7Fjfp0ZBr1KtDRbnfVdmIw
Content-Type: application/json


Media Types

Media types can specify the type of data contained in a given response. The City API currently only supports JSON responses. Requests for XML or other formats will be rejected.

Furthermore, media types can be used to specify a particular version of an API via a custom-defined media type. This allows client applications to be built against a static API and protected from API updates. While we currently do not support such a feature, we may in the future. All requests currently go to our beta API.


Response Types

The City API uses standard responses as described below. In the future, however, some resources may use chunked responses. We may also introduce a streaming API via WebSockets.

Standard

Most City API requests respond with a standard HTTP response. That is, a Content-Length is included in the HTTP response header and a single payload is transferred.

Chunked

Chunked responses use the HTTP Transfer-Encoding header in place of the Content-Length header. You can read about chunked transfer encodings here, but the gist is that 'chunks' of data can be sent to clients before the entire payload is available. This is useful, for example, when transferring large sets of data. This way the client can begin processing streams of data before transfer is complete.


Pagination

Resources that return multiple items will support pagination for traversing results. The ?page and ?per_page parameters specify the page details. page is 1-indexed and, if unspecified, will take a default value of 1. The default value of per_page is typcially 20, but may vary by resource.

Link Header

The Link header will include links to the first, last, previous and next page of results when relevant. For example:

  Link: <https://api.optionscity.com/accounts?page=1&per_page=100>; rel="first",
        <https://api.optionscity.com/accounts?page=4&per_page=100>; rel="prev",
        <https://api.optionscity.com/accounts?page=6&per_page=100>; rel="next",
        <https://api.optionscity.com/accounts?page=10&per_page=100>; rel="last"


Versioning

The City API is always evolving. To ensure that your requests do not fail when the API is updated, we support specifying a static version as part of the HTTP Accept header. Rather than provide media types like application/json or */* (which will work, but always access the latest version of the API), you can specify a media type like the following, which refers to version 2:

application/vnd.optionscity.v2+json

The intent is to never break a request that specifies a version, unless that version is explicitly deprecated. API versions may be deprecated in the future, but we plan to provide ample notice of these changes. As of now, no versions have been deprecated and there are no plans to deprecate. You can check back here for updates on the status of different versions in the future.

You can check here for the current version number, which is also provided in the title of this page...

Current version: 2