High-Level Overview

Simple OpenAPI Usage

The diagram below shows the simplest way to start using Saxo's OpenAPI.

1. Getting a Security Token

All OpenAPI end points require that the calling application pass a valid OpenAPI access token. You can get this by interacting with our security system – there are different authentication flows depending on your application type as described here Security.

2. Calling an OpenAPI REST endpoint

When you have a valid OpenAPI access token, you can call the REST endpoints. This can be as simple as issuing a GET request and providing the OpenAPI access token in the authorization header:

REQUEST:
GET https://gateway.saxobank.com/sim/openapi/port/v1/users/me
 
HEADER:
Accept: */*
Authorization: BEARER eyJhbGciOiJ....
Content-Type: application/json

Details of how to use the Request/Response endpoints can be found here: OpenAPI Request/Response.

OpenAPI Service Groups

OpenAPI Resources are grouped into Service Groups such as the 

• Reference Data group giving reference information about the instrument universe, exchanges, sectors etc.
• Portfolio service group giving information about the current status of clients and their accounts in the live trading system, such as open orders, positions, balances etc.
• Trade service group giving streaming prices and the ability to place orders and trades.

Details of the available service groups can be found here: Service Groups.

Batching

Combining calls to resources within the same service group into a multi-part message (called "batching") is described here: Batching Requests.

Streaming

Many OpenAPI resources also support streaming which updates quotes, positions, orders, balances etc. without your client application having continually polling the OpenAPI, resulting in much less network traffic and lower latency.

To use streaming:

1. Establish connection to the streaming server.
2. Setup one or more subscriptions to specify what you want to subscribe to.

1. To establish a streaming connection

We are using websockets to connect with the server. See the environments article for a list of endpoints.

A simple example of doing this against the simulation environment is shown below:

var accessToken = "eyJhbGciOiJ.....";
var contextId = "someUniqueId"; 
var streamerUrl = "wss://gateway.saxobank.com/sim/openapi/streamingws/connect";

_connection = new WebSocket(streamerUrl + "?authorization=" + encodeURIComponent("BEARER " + accessToken) + "&contextId=" + contextId);

The _connection object has callbacks for messages received, date updates, connection loss etc.

2. Setting up subscriptions

When a streaming connection has been established, you need to explicitly subscribe to receive updates by posting to a  /.../{resource}/subscriptions endpoint. When you do this, you immediately receive a response containing a full snapshot of the resource.

An example of doing this on the portfolio/balances endpoint:

HEADER:
Accept: */*
Authorization: BEARER eyJhbGciOiJ....
Content-Type: application/json
 
POST https://gateway.saxobank.com/sim/openapi/port/v1/balances/subscriptions
{
........
}
 
 

3. Listening for resource updates

When the snapshot has been generated and has been returned to the client in the HTTP Response, the OpenAPI service group starts monitoring the resource. At regular intervals (up to 3 times/second), OpenAPI will compare the current state to the previous state and if they are different, a delta is calculated and returned over the streaming channel.

About Streaming

Note that streaming is an advanced topic, the above is just short introduction. A few tips when using streaming:

• You can group subscriptions on a tag, so you can unsubscribe many related subscriptions through a single call.
• You must be prepared to handle various error-events coming through the streaming channel.
• And in general you must be careful to handle deltas correctly when updating your model in your client application.

Examples in JavaScript can be found on Github.

A number of detailed articles about streaming can be found here.