REST trading API guide

Overview

REST (Representational State Transfer) is the standard way of accessing resources over the web. It is done through four standard HTTP operations:

• GET
• POST (create)
• PUT (update)
• DELETE

For example, when you enter http://www.ig.com into the browser address bar, the browser issues a GET HTTP request on the web page resource at that address, and returns a web page as a response. Similarly, in the case of our API, a GET HTTP request to https://api.ig.com/gateway/deal/positions would return a list of open positions on the active account.

The R in REST refers to the representation (or format) of the resource being accessed. In our case, it is the web-standard JSON (JavaScript Object Notation) format.

If you have an IG demo account, we recommend that you run the sample application on the left, logging in using your demo account, and selecting 'Show HTTP' to see the API HTTP requests and responses in action.

HTTP requests

Section	Component
Action	HTTP operation	GET - retrieve a resource PUT - replace a resource POST - create a resource DELETE - delete a resource
	HTTPS	The secure web protocol. It ensures that requests are encrypted between the application and the API
	demo-api.ig.com/gateway/deal	The API gateway location. Use api.ig.com instead of demo-api.ig.com for live account access
	/positions	The address of the resource you are accessing, positions in this case
Request Header	X-IG-API-KEY: k	The API key k (obtained from My Account on our dealing platform) is how we identify and authorise the calling application
	CST / Authorization	A valid access token identifying the client.
	X-SECURITY-TOKEN / IG-ACCOUNT-ID	A valid account token or account id identifying the client's current account.
	Content-Type: application/json	Request format type. This should always be set as indicated to json only
	Accept: application/json; charset=UTF-8	Response format type. This should always be set as indicated to json only
	Version: v	API version v (defaults to 1, if not specified)
Request Body	Only required for PUT or POST requests	JSON format

Authentication and authorisation

There are currently two mechanisms for logging into and accessing the API.

• POST /session v1 and v2 return a CST header with a token identifying a client and an X-SECURITY-TOKEN header with a token identifying the current account. These headers should be passed on subsequent requests to the API. Both tokens are initially valid for 6 hours but get extended up to a maximum of 72 hours while they are in use.

• POST /session v3 returns OAuth access and refresh tokens which the user can pass in subsequent API requests via the Authorization header, e.g.:

  Authorization : Bearer 5d1ea445-568b-4748-ab47-af9b982bfb74

  The access token only identifies the client so users should also pass an IG-ACCOUNT-ID header to specify the account the request applies to, e.g.:

  IG-ACCOUNT-ID : PZVI2

  The access token is only valid for a limited period of time (e.g. 60 seconds) specified by the login response.
  "oauthToken": { "access_token": "702f6580-25c7-4c04-931d-6000efa824f8", "refresh_token": "a9cec2d7-fd01-4d16-a2dd-7427ef6a471d", "scope": "profile", "token_type": "Bearer", "expires_in": "60" }
  The refresh token can used to acquire a new access token, either before or after the access token has expired but please note that the refresh token does also expiry some time after the access token has expired (e.g. 10 minutes). A call to refresh an access token will also return a new refresh token.The scope for individual clients is always profile which allows full access to the user's account.

FIQL query filters

FIQL (https://tools.ietf.org/html/draft-nottingham-atompub-fiql-00) defines a syntax for expressing filters on entries of a web feed so it can be used to query resources. The activity history is one of the endpoints supporting this syntax and provide a way to query activities, e.g.:

This query returns all activity history item representing a cancelled order either via the public Web or FIX API.

HTTP response

Section	Component
Response Header
	X-REQUEST-ID	Identifies the request
HTTP status code
	200	request executed fine
	401	access denied
	500	server failure
	...
Response Body	Request results, if any.	JSON format. In the event of an error, the body will be of the form: { "errorCode" : "the error code" }

Paging

Paging applies to a subset of endpoints returning a list of entries, such as e.g. historical data. A metadata section on the response should provide paging details:

In this case "next" will provide a link to retrieve the next page of data.

Errors

Error responses contain a 4xx or 5xx HTTP status and a body with the following format:

User errors caused by e.g. malformed json or invalid requests will be returned as HTTP 4xx errors. The suffix of error codes in validation failures can change depending on the request field that caused the failure, e.g. "invalid.request.forceOpen" indicates that the value on request field "forceOpen" was invalid.