Quick Start Guide - Market Data Gateway (MDG) APIs...File Name Quick Start Guide - Market Data Gateway (MDG) APIs_v1_1 external.docx Contents Introduction for developers and other

Quick Start Guide - Market Data Gateway (MDG) APIs

By: Juergen Rolf

Revision Version: 1.1

Revision Date: 2018-03-27

Company unrestricted

Quick Start Guide MDG APIs


Copyright © 2018 FactSet Digital Solutions GmbH. All rights reserved.

Revision Version 1.1, Revision Date 2017-03-27, Author: Juergen Rolf www.factset.com | 2

Document Information

Document Details

File Name Quick Start Guide - Market Data Gateway (MDG) APIs_v1_1 external.docx

Contents Introduction for developers and other technical personnel to the MDG and the basic concepts around accessing it.

Author Juergen Rolf

Version 1.1

Date 2018-03-27

Intended Audience

This document is an introduction to the Marked Data Gateway (MDG) platform and its APIs. The intended

audience are project managers and developers who want to start building financial applications that use

the data and functionality provided by the MDG.

Revision History

Revision Date Version Notes Author Status

2017-12-04 1.0 Initial Release J. Rolf Released

2017-03-27 1.1 Adjustments for external release

J. Rolf Released

References

No. Document Version Date

1. MDG Foundation API Client Library PHP - Installation Guide external

1.1 2018-03-27





Table of Contents

Document Information ............................................................................................................................. 2

Document Details ................................................................................................................................................. 2

Intended Audience ............................................................................................................................................... 2

Revision History ................................................................................................................................................... 2

References ........................................................................................................................................................... 2

Table of Contents .................................................................................................................................... 3

Terminology ............................................................................................................................................. 4

Prerequisites ........................................................................................................................................... 5

1 How to Read this Document ............................................................................................................. 6

2 Solutions with the MDG .................................................................................................................... 6

2.1 Solution Overview ......................................................................................................................................... 7

2.2 Access to the Market Data Gateway with the Foundation API ..................................................................... 8

3 Market Data Gateway Server Components ....................................................................................... 9

3.1 Frontgate ....................................................................................................................................................... 9

3.2 Customized API Service ................................................................................................................................ 9

3.3 Endpoints ....................................................................................................................................................... 9

4 Clients ............................................................................................................................................ 10

4.1 Abstract Description of Client Types ........................................................................................................... 10

4.2 Supported Technologies ............................................................................................................................. 10

5 Essential Concepts ......................................................................................................................... 14

5.1 Credentials .................................................................................................................................................. 14

5.2 Request and Response Calls and Pushed Data ......................................................................................... 14

6 Next Steps and further Readings .................................................................................................... 15





Terminology

Term Description

API Application Programming Interface, a piece of software that exposes data from a system to another application.

CAS Customized API Service – a server that contains customer-specific setups for back end services and hosts endpoints.

Client An application that requests data from the MDG. Also a company that is a customer of FactSet Digital Solutions.

Endpoint A piece of software that is located on a customized API service (see CAS). It provides an abstraction layer for back-end requests and advanced business logic.

Foundation API

The set of defined requests and responses that the MDG exposes. Other programs can use these to interact with the MDG.

HTML Hypertext Markup Language, a language that describes documents, predominantly for display of web sites.

HTTP Hypertext Transfer Protocol, the Internet’s most common transfer protocol on the application layer.

HTTPS Hypertext Transfer Protocol Secure, a layer that secures transmissions over HTTP.

MDG Market Data Gateway, the market data platform of FactSet Digital Solutions.

PTL A proprietary protocol definition language, abbreviation for Protocol Template Language. This definition language defines the internal serialization format of messages.

TCP Transmission Control Protocol, a common connection-orientated protocol used e.g. on the internet.





Prerequisites

This document should be read in conjunction with other documents mentioned in the text and will guide you

to understand the MDG APIs.

You need to have access to the following resources to make use of all aspects:

1. Login to the endpoint reference tool (https://endpointreference.mdgms.com/login)

This is a web-based tool that contains the documentation of the endpoints with input- and output

specifications.

2. Application- or User Credentials for MDG data

Credentials that allow to log on to the MDG and to query FactSet Digital Solutions’ API services

(e.g. in order to receive market data that is defined for a specific customer application or a user

inside an application).

If you are missing any of the above items, please contact your FactSet Digital Solutions contact to get

access to the missing resources.

https://endpointreference.mdgms.com/login





1 How to Read this Document

The introductory documentation of the MDG APIs is split into two parts:

As indicated above, each reader should start with Part I – the Quick Start Guide (this document) and

afterwards pick his desired technology from Part II – the individual Technology Guides. Each of these

Technology Guides carries information on a specific client library using a different technology (e.g. PHP,

Java, etc.).

2 Solutions with the MDG

The Market Data Gateway (MDG) is the central market data platform of FactSet Digital Solutions. It

imports, consolidates, enriches and processes a wide range of financial data from a multitude of sources.

The data is then delivered to client applications in a normalized data format.





2.1 Solution Overview

This section aims at providing an initial overview of a possible solution setup. More detailed information on

the involved components can be found in the remainder of this document.

Most solutions adhere to the following pattern: A client program connects to the central server, the

Frontgate server in the FactSet Datacenter. The client then sends a request for market data or business

logic. The Frontgate server forwards the request to the Customized API Service (CAS) server. The CAS

server hosts endpoints encapsulating the requested business logic. The endpoints obtain data from and

perform calculations in specialized backend servers, aggregate the data, and create the response

containing the results. The response is then routed back via Frontgate to the calling client.

The following picture provides an overview of this generic setup and the involved communication between

these components:





2.2 Access to the Market Data Gateway with the Foundation API

The interface that the Frontgate server (see chapter 3.1, for more information) exposes to clients is called

the “MDG Foundation API”. This interface defines all messages that the MDG platform accepts and

processes.

Several technologies are supported by Frontgate to exchange messages. These serve a large variety of

use cases. The server features different protocols (TCP, HTTPS, WebSocket) and different serialization

formats (binary PTL and JSON). These options are described below.

Stateful Connections

The MDG API primarily uses stateful, long-lived connections where both sides are allowed to

spontaneously send messages to communicate with each other in a bi-directional manner.

WebSocket

This connection type may exchange all MDG Foundation API messages in the supported serialization

formats:

• Plain PTL (binary)

• JSON

• JavaScript compatible JSON

Binary PTL over TCP

This connection exchanges all MDG Foundation API messages in a binary format directly over a TCP

socket. It is the most efficient data exchange mechanism and is used by most client libraries provided by

FactSet Digital Solutions.

Request and Response via HTTPS

A request / response interface via HTTPS exists, which is targeted at lightweight applications that do not

need the robustness and speed of stateful connections. The only protocol supported in that case is HTTPS.

This request / response interface therefore provides easy access to the endpoint layer (see 3.3). The





corresponding requests / responses are internally translated into Foundation API HighLevelRequests

/HighLevelResponses.

3 Market Data Gateway Server Components

3.1 Frontgate

The Frontgate server is the only component that is directly exposed to clients. It receives client requests,

performs authentication, routes requests to different backend servers, caches and returns responses

appropriately.

3.2 Customized API Service

The Customized API Service (CAS) is a backend server that hosts the set of endpoints for a given

customer. The Frontgate server forwards authenticated requests to the relevant CAS.

The list of endpoints that are available to each customer can be seen on the official documentation website

for endpoints. You may access the official documentation via the Endpoint Reference at:

https://endpointreference.mdgms.com/login.

3.3 Endpoints

An endpoint is a piece of software that is registered and executed in the Customized API Service. It

provides access to MDG data and underlying business logic. Endpoint’s input parameters are easy to

understand and directly reflect the intended business purpose. Endpoints deliver JSON format in their

responses. Thus, endpoints serve as an abstraction layer encapsulating multiple or complex back-end

requests and calculations.

Generic Endpoints

These endpoints allow access to specific tools or standardized API based products of FactSet Digital

Solutions.

For example: Get all available regulatory documents for an instrument from the FactSet Digital Solutions

“Regulatory Document and Data Service”.

Customer Endpoints

Customer endpoints implement business logic that is based on specific requirements for a given customer.

Thus, customer endpoints are per definition part of a bespoke customer solution. The development of

endpoints of this type can be conducted by FactSet Digital Solutions on request and is not covered by the

basic fees for the API usage.

An example for such an endpoint might handle the following business logic: Get the “best price" for an

instrument identified by ISIN, according to rules defined by a customer. The logic of “what constitutes the

best price" is defined by a particular customer and thus would be implemented in a (bespoke) customer-

https://endpointreference.mdgms.com/login





specific endpoint. Such an endpoint would allow for an easy retrieval of the best price according to this

bespoke definition.

4 Clients

4.1 Abstract Description of Client Types

“Clients” in an MDG solution is any form of software that requests and uses data from the MDG. Usually,

clients run on an end user device or a web server and so they can be categorized based on the device and

technology that is used.

For example, Web Server- and Terminal Applications will use an API library in a local programming

language to connect to the MDG (for more information, refer to the documentation: Part II – Technology

Guides), while browser applications will frequently use a more lightweight JavaScript Library and a mobile

application might even request data directly via the HTTPS request/response interface.

4.2 Supported Technologies

This chapter gives an overview of the different technologies and API libraries that are provided by FactSet

Digital Solutions in order to access the MDG. The main distinction is between the dedicated client libraries,

which constitute the standard case and a simplified HTTPS scenario, which is intended only for exceptional

cases.

Dedicated Client Libraries

This is the standard use case. An application that runs in a specific programming language makes use of a

programming language-specific client library to retrieve data via API calls. These libraries are provided for

a set of selected technology stacks and are called “Foundation API Client Libraries”. They are described in

detail in Part II of the documentation, the individual Technology Guides.

The main advantage of these libraries are:

• They provide a ready-made implementation for the protocol handling

• They provide a mechanism to subscribe to data and thus, to receive continuous updates (see

chapter 5.2 for further details)





• They may contain a client-side cache that works on the protocol level. Client libraries that feature a

cache are also referred to as “extension modules”.

• And they contain other convenient methods, which will ease the usage of the API for developers.

Example Scenario

The image below shows an example setup in which the Foundation API Client Library for PHP is used: A

Web Server that runs PHP uses that library to request data from the Frontgate server. With the data that it

receives, the PHP server compiles an HTML page and delivers that to a client device. The client renders

the HTML document in a browser and displays the final view to the end user.

Please note that this is just one example for the usage of one of the provided client libraries. There are

numerous variants of solution setups. Please consult with your FactSet Digital Solutions contact prior to

your implementation start to ensure that the architecture of your individual setup contains the optimal

choice of APIs and technologies.





The following list contains the client libraries provided by FactSet Digital Solutions:

API Library API Technology / Connections

API Scenarios

Foundation API Client Library - PHP

PTL protocol via TCP A PHP-based server can use this library to connect to the MDG and create static HTML pages.

Foundation API Client Library – Java

PTL protocol via TCP A java-based server can use this library to connect to the MDG and to process the data in its services.

Foundation API Client Library - JavaScript

PTL protocol via TCP / JSON

A JavaScript-enabled frontend can use this library to connect an HTML5 page in a browser to the MDG, so that the page can receive updates from the MDG.

Plain HTTPs Calls

For use cases where dedicated client libraries are not an option, a request / response interface exists,

which allows for the exchange of so called MDG Foundation API HighLevel messages. This interface is

suitable for lightweight applications that do not need advanced capabilities such as stateful connections

supporting the push functionality.

This interface can be used from clients with any technology that allows to make HTTPS calls to the MDG. It

is therefore very simple and technology-agnostic.

This interface requires a special authentication step that is based on a high-level-token. The token must be

obtained from a trustworthy source like a server in a datacenter - that means it cannot be initiated from an

unknown device or browser on the Internet.

High-Level-Token Based Authentication

When a client library is used for the communication from clients to the MDG, the authentication handshake

happens via a stateful connection that has to be obtained.

In contrast to that, when utilizing the simple HTTPS interface, authentication must take place before the

first data request. For this case, the clients have access to a dedicated Authentication Token Server. It

accepts MDG credentials and returns a token, which allows further requests to the Frontgate server.

The Authentication Token Server and the Frontgate server are both located on the FactSet Digital

Solutions datacenter, as shown in the following overview:





Example Scenario

In this case, data is requested with a series of plain HTTPS calls. Clients can be any form of device

No stateful connection is created between the clients and the Frontgate server, as depicted below.





Available Protocols

The following protocols and encoding methods are available if no Client Library is used.

API Technology / Connections

API Scenarios

JSON over HTTPS requests

A mobile application of any technology can use this to request a snapshot of data (no push possible).

5 Essential Concepts

5.1 Credentials

The MDG authentication mechanism knows two different levels, on which a client can gain access:

a) User-Level and

b) Application-Level

User-Level Credentials

User-Level authentication is used when end users are distinguished in the application. The individual user

has a user name and password and the market data that is accessible can be tailored to the data privileges

of the individual user. Please note that a user in this case does not necessarily have to refer to an

individual person. It could also refer to a technical user.

Application-Level Credentials

The Application-Level authentication is used when a scenario does not include individual users.

Examples of that are:

• A server makes request on behalf of an anonymous user group, like on open website where user

are not logged in.

• A server gathers data for processing independently of any users for a back end application.

• An application requires functionalities that access data across the boundaries of one user, like e.g.

if an administrative user shall see an overview over the portfolios of many users.

5.2 Request and Response Calls and Pushed Data

Data from the MDG is typically obtained by exchanging request and response messages. Some of these

requests support continuous updates on the data received in a response. This update mechanism is

referred to as “subscription”, also known as “push”.





Request and Response Data

In the “Request and Response” case, the MDG answers subsequent requests for data with one finite

response each.

In the following image, the client makes multiple requests for data and receives one response for each

request.

Subscriptions / Pushed Data

In the subscription case, the MDG returns an initial response and then continuously sends update

messages. These update messages contain data that has changed on the platform and is related to the

request. The order and integrity of the update messages is guaranteed by the platform. A connection to the

platform is required to support a subscription.

Some endpoints (see section 3.3) provided by FactSet Digital Solutions also support subscription based

push updates. These endpoints are marked as “Pushable” in the official endpoint documentation, which is

accessible via the Endpoint Reference (see section 3.2).

6 Next Steps and further Readings

This chapter concludes Part I – Quick Start Guide of the documentation for the MDG Foundation API. As

described in the chapter “How to Read this Document”, it is recommended to continue with Part II – the

individual Technology Guides. Also see the “References” section of this document for the available

documentation for other APIs.

Documents

Quick Start Guide - Market Data Gateway (MDG) APIs...File Name Quick Start Guide - Market Data Gateway (MDG) APIs_v1_1 external.docx Contents Introduction for developers and other