API Documentation

Introduction

The SAXO API is a collection of web services that are used by Saxo, Saxo Partners and 3rd party developers to access and work with data on the Saxo infrastructure.

With the Saxo API, one should be able to search through all products, work with user product lists and search through authors by using simple HTTP standards.

This document is primarily written for other developers of different skillsets but with the clear goal of explaining how the Saxo API works and how other developers can work with it.

How to access the API

Everything related to the API will be found on the SAXO API Documentation here:

http://api.saxo.com/ ( you are here now ) 

To access the latest API, please visit the Saxo API page, which holds the API Reference Documentation and also happens to be the API endpoint:

http://api.saxo.com/v1/

To gain access to the Saxo API you need an API Key. To apply for an API key, please feel free to contact Saxo at api@saxo.com.

The Basics

Saxo API will give you the tools you need to be able to access Saxo data and functions, by just using simple HTTP calls to the API Server. The API is split into independent services, that each will operate in its own domain.

The API is built around a couple of Services, where each service more or less implements the 7 supported Service Methods. It will of cause not be required for each service to take full advantage of all the methods, but just as well, it will not be possible to implement more than those 7 methods.

For each service the API currently supports the following service methods:

A description of each of the above service methods, will be mentioned later in this document.

Some services currently supported by the Saxo API:

By calling the service using different criterias, the service will output different results. But for the product service, the product itself will be the resource and the criteria will specify the reference and specifications on how to reference each given resource.

The Architecture

The Saxo API, although only in version 1, is striving to be a full-blown REST Service that will benefit from the elegant nature and almost naive approach to data handling.

All communication involved will be transferred through the HTTP protocol. But instead of implementing a new protocol on top, like it is seen with SOAP or XML-RPC, this API will take use of the HTTP standard through REST.

HTTP is mostly used to handle web pages through a browser; it is something that people are very used to. So to navigate webpages using URL's are very common practice, especially by today's web developers. The URL is structured with a {hostname}, a {path} and a {querystring} that complements with the URI standard like this:

HTTP GET: http://{hostname}/{path}?{querystring}

Saxo REST API basically uses the path as a reference to the location of the sources and the querystring to filter and search through the resources. In the SAXO API, the URL will look like this:

{httpmethod} : http://{hostname}/{version}/{servicename}/{handle}.{mediatype}?{criteria}

The httpmethod, is how we want to access the resources. The Hostname is the name of the API server and Version is referring to where the version of the API’s endpoint that is being located. Servicename is the name of the service and handle is used to address a given resource, resource collection or values. The media type is the file extension, used to describe what format data are being exchanged in. And finally the criteria and other required queries like API key are used to specify which resources are being filtered.

The criteria are a typical URL querystring, with a string containing a variable list of string/value pairs combined with the usual & character.

?parameter1=value&parameter 2=value&parameter3 = value

A typical URL could look like:

HTTP GET http://dev.saxo.com/v1/products/products.xml?key=XYZXYZXYZ&sort=Popular&limit=20&contributoralias=dan-brown&rating=3

It will search for 20 products using the product service, where the author alias is "dan-brown", has at least 3 star user reviews and sorted by the most popular books first. To be able to do that, an API Key "XYZXYZXYZ" are being used.

For most developers new to REST, It can often be compared to a relational database in typical SQL, where the above REST call then would be written in SQL as:

		pseudo SQL:
		SELECT *
		FROM Products
		WHERE contributoralias=”dan-brown” and ratingavg>=3 ORDER BY Popularity DESC

By combining the path and the QueryString, the URL in REST is almost working as a Query Language.

Another REST query could be:

It will fetch the product with id 12345678 using the API Key XYZXYZXYZ . It is of cause worth noting that the handle “12345678” is because we are referring directly to the resource instead of searching for it as we did in the previous example.

HTTP GET http://dev.saxo.com/v1/products/12345678.xml?key=XYZXYZXYZ

The above query will in SQL be written just as simple as:

		SELECT *
		FROM Products
		WHERE ID = 12345678

And just as SQL where you can select, update, delete and insert data using different SQL Statements. You can in REST use the different HTTPMethods to handle your "queries"

To perform a delete method in Saxo REST API, using the HTTP Method DELETE, the request would be:

	HTTP DELETE http://dev.saxo.com/v1/products/12345678.xml?key=XYZXYZXYZ
		

And to perform the equal operation in SQL, it would be written as:

	DELETE
	FROM Products
	WHERE ID = 12345678
		

Media Types

When transmitting data to and from the API it will as mentioned before, be done using the HTTP protocol. To be able to support different clients and different business cases, it is possible to transmit the data using different standard formats.

Extension Supported
.xml full
.json or .js Only read data ( GET, FIND, Facettes and Count)
.rss or .atom planned
.csv Only read data ( GET, FIND, Facettes and Count)
.pdf planned

The obvious choice for data format is of cause XML and for that Saxo has implemented a custom XML scheme.

The Criteria

As mentioned the criteria is represented by the handle and the querystring in the URL.

Although each service will map its own criteria, there are different some base criteria parameters, that will be available on each service.

Criteria Parameter Description
Id Directly reference to the resource
Alias Most resources will have an alias to search on
Page In the given result set of resources, what page is currently being viewed.
Limit Number of resources to be returned in the given result set. Is also referred to as Page Size
Query A text string, used to search through all the given services resource.

The Resource

As with the criteria, the resource will also be different in each service, and will also share a common attribute called ID. An ID will always be bound to a resource in a Saxo API Service.

Beside that the resources are simple data representations of data objects, easily transmitted and used in different contexts. A product resource, will ofcause have an ID, but then have attributes for title, descriptions, authors, ISBN13, prices, etc..

The Service Mehods

To map the different HTTP methods towards the Saxo system, the methods will be mapped towards a couple of service methods.

Each service will support the following Service Methods:

Service Method Handle HTTP Method Arguments Returns
GET {resourceid} GET {resourceid} Resource
FIND {servicename} GET {criteria} List of Resources
CREATE {servicename} POST {resource} Resource
UPDATE {resourceid} PUT {resource} Resource
DELETE {resourceid} DELETE {resourceid} NONE
FACETTES "facettes" GET {criteria} List of facettes
COUNT "count" GET {criteria} Number

GET

Retrieve a single resource from a given service using the matching resourceid

	Example: Retrieve a single product with productid 21904 from the product service.
	HTTP GET
	URL http://{domain}/{version}/products/21904.xml?key=XYZXYZXYZ
	

FIND

Find/Search for resources from specified criteria

	Example: Look for products written by author "Dan Brown" and products of the type "Book"
	HTTP GET
	URL http://{domain}/{version}/products/products.xml?key=XYZXYZXYZ&contributoralias=dan-brown&productformat=book
	

CREATE

Create a new resource through the service.

Example:Create a new product using the product service:

	HTTP POST
	URL http://{domain}/{version}/products/90210.xml?key=XYZXYZXYZ

UPDATE

Update / Change attributes on a resource in the service

Example: Change the book title by pushing a changed resource to the update method.

	HTTP PUT
	URL http://{domain}/{version}/products/90210.xml? key=XYZXYZXYZ

You only need to post the resource containing the attributes that are being changed

DELETE

Delete/Remove resource from a service

	Delete a product
	HTTP DELETE
	http://{domain}/{version}/products/90210.xml?key=XYZXYZXYZ

FACETTES

Group the filtered search results into the related entities and attributes

	HTTP GET
	http://{domain}/{version}/products/facettes.xml? key=XYZXYZXYZ

COUNT

Count the number of resources matching a given criteria.

Example:Count the number of products by contributor “Dan Brown”

	HTTP GET http://{domain}/{version}/products/count.xml?
	key=XYZXYZXYZ&contributoralias=dan-brown