DataScope Select - REST API

Quick Start

Last update July 2019
Environment Windows
Language C#
Compilers Microsoft Visual Studio 2013
Prerequisites DSS login, internet access

Microsoft .Net Framework 4.5+ 
Source code Download C# Example Application

Quick start purpose

The purpose of this Quick Start is to get the DSS (DataScope Select) REST API C# example application to run, and understand how to use it.

This application demonstrates the DSS API at a high level, without requiring any coding; it is thus ideal to help you discover the API, hence its use here.

At the same time, it is a very complete learning tool, which complements the tutorials with more code samples and easy views on the requests and responses exchanged between the application and the DSS hosted server.

This application is therefore very useful to all programmers; it is not limited to those who decide to use the .Net SDK and program in C#.

We therefore recommend coming back to it after following the tutorials, once you start coding.

 

Table of contents

 

Additional details on the prerequisites

A DSS user account (user name and password) is required, because this application uses it to authenticate to the DSS server.

An internet connection is required to download the software, and run it, as it connects to the DSS server.

Microsoft .Net Framework 4.5+ should be pre-installed.

We recommend running the application from Microsoft Visual Studio, but in case of need the application can also be run without Microsoft Visual Studio (instructions below cater for both use cases).

 

The DSS REST API C# example application

This application is very useful and powerful:

  • It demonstrates the functions of the DSS REST API, through use cases illustrated with real functional code.
  • It displays the HTTP requests and related responses, so you can see the data formats that are returned, and get a feel of response times.
  • It contains code snippets you can copy to use in your own code, to deliver faster results.

We recommend using this C# example application, it will jumpstart your learning and coding.

 

Side note: what is the DSS Web GUI ?

The DSS web GUI is what you get when connecting with a browser directly to the DSS server:

It allows to manually request data from the DSS server, by creating instrument lists, report templates and schedules, and then retrieve the resulting extracted files:

The API can perform the same tasks as the GUI (and more), programmatically. Prior GUI knowledge helps understand the API. The tutorials use the GUI to view results of API usage. For DSS web GUI help, see under: Help - Get Help:

DSS GUI Help

 

DSS REST API C# example application: installation

Let us get the DSS REST API C# example application to run.

We shall start from scratch, by creating a work folder, with a subfolder for software downloads, and another one for this quick start:

You can name all these folders as you like.

Download the C# Example Application, save it in your Downloads folder:

 Copy the contents of the zip file into the folder you created for the quick start:

 

DSS REST API C# example application: configuration

Check the DSS server URI, in the configuration file. The configuration file is not the same one if you are running from Microsoft Visual Studio or directly running the executable program.

If you have Microsoft Visual Studio

Edit file QuickStart\app.config:

If you don’t have Microsoft Visual Studio

Edit file QuickStart\bin\Release\Dss.Api.Examples.exe.config:

 

Running the DSS REST API C# example application

If you have Microsoft Visual Studio

Double click on QuickStart\Dss.Api.Examples.sln to open the project in Microsoft Visual Studio.

Then click on 

The first time you start the project, NuGet packages are restored, and the project is built. This can take several minutes.

Then it runs.

If you don’t have Microsoft Visual Studio

Double click on QuickStart\bin\Release\Dss.Api.Examples.exe to manually run the executable program.

 

Entering your DSS credentials

The example code prompts for your DSS credentials:

DSS Example App Login screen

Enter your DSS user name, your password, and then click on the "Login" button.

After that the example application appears:

 

DSS REST API C# example application: capabilities

This example code is very powerful. It gives you a window on all the functionality of the DSS REST API.

On the left there is a menu containing several sections, which cover all the steps of a typical DSS session:

  • User authentication
  • Instrument search (if required)
  • Defining an instrument list
  • Defining a report template (report type, format, output and data fields)
  • Scheduling the extraction execution (immediate or at a specific time, recurring or not)
  • Retrieving the extraction results (the extraction files contain the data)

 

Each of these sections contains one or several examples, covering many use cases:

Authentication

When connecting to the DSS servers, all applications must submit a user name and password. You entered those when starting this example application. Once authenticated, a session token is associated to the context.

Search

It is possible to search for instruments, in case their identifiers are not known.

Instrument List Examples

Defining a list of instrument identifiers, for which we will request data.

Report Template Examples

Defining a report template, whose format and output data fields vary depending on the type of data we want.

Data fields can of course be selected, to optimize data retrieval and subsequent processing.

On Demand Extractions and Schedule Examples

To retrieve data we schedule a data extraction execution.

An extraction can be scheduled to be on demand and immediate.

Alternatively, it can also be scheduled for a later time, like after market close, and run either recurrently or as a single occurrence.

Scheduled Extractions

Once a scheduled extraction has completed, we can retrieve the extraction results, which contain the requested data.

This, like all the above, is done using the API. There is no need to FTP result files (it is still possible to do so, but using the API is more practical).

Standard Extractions

These are for eventual subscriptions to other data types (Ownership and Profiles, StreetEvents, Insider, TRTH Venue by Day).

These API calls can list available subscriptions and packages, and list and download package deliveries (individual data files) without using FTP.

These calls are out of scope for this Quick Start and the Tutorials.

 

DSS REST API C# example application: usage

Let us run one of these examples. For instance, in the left menu area, let us click on On Demand Extractions to open it up, and then click on Create Time Series. Then click on C# Full. This one is for an immediate time series extraction:

To run the sample, click on the play button: 

The full code, with explanatory comments, is displayed in the lower right window. Everything you need is right there; all you need to do is copy/paste code samples into your own projects, as required. We will not attempt to understand the code now; coding details are covered in the comments in the code, and in the tutorials.

The execution time depends on the actions, the amount of data retrieved, and the server load.

Each step of the code appears in the top window, with:

  • The elapsed time since run start.
  • The method.
  • The step number.
  • The request.
  • Its status.
  • If it is a GET or a POST.
  • The execution time of the individual step.

 

Once the sample has run (depending on the sample, run time can be anything from a few seconds to a minute or more), we can select a step in the top window, by clicking on it:

The related code snippet is highlighted in the C# full tab, which contains the complete code.

 

Clicking on the C# Snippet tab limits the display to the code related to the selected step, extracted from the full code:

 

Clicking on the HTTP tab displays the underlying REST request and response:

We see the first step was a request for a list of valid data field types, for Timeseries pricing.

The response contains the requested list of valid data field types.



Selecting a different step in the top window allows seeing the related C# Snippet and HTTP messages.

 

Storing your DSS credentials

If you run the example program often, you might want to store your DSS credentials to avoid entering them manually. This can be done in the configuration file. The example code is built to detect if the credentials were set in the configuration file and, if not set, to prompt for them at run time.

Note: the configuration file is not the same if you are running from Microsoft Visual Studio or directly running the executable program.

If you have Microsoft Visual Studio

Edit file QuickStart\app.config:

If you don’t have Microsoft Visual Studio

Edit file QuickStart\bin\Release\Dss.Api.Examples.exe.config:

 

Enter your DSS credentials in that file

Replace “YourUserId” and “YourPassword” with your DSS account user id and password, in the locations highlighted in the screenshot below:

 

To learn more

To gain further knowledge, follow the tutorials, which explain coding with the DSS REST API in detail, and deliver further tips, tricks, and code snippets.

We also recommend you spend some time playing around with this example program.

It is a great tool to easily learn the DSS REST API, and build your own applications by reusing code snippets. The knowledge of what results will be delivered, and their format, will help you further manipulate the data as required.