Foundation API Client Library PHP – Usage Examples By: Juergen Rolf Revision Version: 1.2

Home , Library (computing)

Revision Date: 2019-09-17 Company Unrestricted

Foundation API Client Library PHP – Installation Guide

Document Information

Document Details

File Name MDG Foundation API Client Library PHP - Usage Examples_v1_2 external.docx

Contents Usage Examples and Tutorial introduction for the Foundation API Client Library - PHP

Author Juergen Rolf

Version 1.2

Date 2019-09-17

Intended Audience This document provides a few examples helping the reader to understand the necessary mechanisms to request data from the Market Data Gateway (MDG). The intended audience are application developers who want to get a feeling for the way they can request and receive data from the MDG.

Revision History

Revision Date Version Notes Author Status

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

2018-03-27 1.1 Adjustments for external J. Rolf Released release

2019-09-17 1.2 Minor bugfixes J. Ockel Released

References

No. Document Version Date

1. Quick Start Guide - Market Data Gateway (MDG) 1.1 2018-03-27 APIs external

2. MDG Foundation API Client Library PHP – Installation 1.2 2019-09-17 Guide external

Foundation API Client Library PHP – Installation Guide

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 Application Setup ...... 7 2.1 Common setup of a PHP based application ...... 7

3 Verification of the Installation ...... 8 3.1 Integration of Foundation API class files ...... 8 3.2 Configuration of the __autoload() function ...... 9 3.3 Connecting via the PHP extension module ...... 9

4 Sending an Example Request ...... 11 4.1 Example Request to the “Echo” Endpoint from PHP Code ...... 11 4.2 Error Handling ...... 14

5 The PHP Client Library Tutorial ...... 14 5.1 Requests to Endpoints ...... 14 5.2 Running the Client Library PHP Tutorial ...... 15

6 Conclusion and Outlook ...... 17

Foundation API Client Library PHP – Installation Guide

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 The set of defined requests and responses that the MDG exposes. Other API 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 binary serialization format of messages.

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

Foundation API Client Library PHP – Installation Guide

Prerequisites

This document should be read in conjunction with other documents mentioned in the text. It will guide you to understand the usage of the MDG Foundation API Client Library for PHP. You need to have access to the following resources to make use of all aspects: The installation package of the MDG Foundation API Client Library for PHP, including its documentation- and tutorial folders. 1. Login to the endpoint reference (https://endpointreference.mdgms.com/login) This is a web application 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.

Foundation API Client Library PHP – Installation Guide

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 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.). This document is part of the Technology Guide (Part II – documentation) of the MDG Foundation API Client Library for PHP. The MDG Foundation API Client Library for PHP allows clients to connect to and communicate with FactSet Digital Solutions’ MDG Platform. This document provides a step-by-step guide covering usage examples of the client library on a target host. The remainder of the document is structured as follows:

• Chapter 2 describes the general setup of an application that uses the MDG Foundation API Client Library for PHP. • Chapter 3 provides details of how a connection can be initialized to FactSet Digital Solutions’ MDG Platform. • Chapter 4 provides details of how an endpoint can be requested from the MDG platform. • Chapter 5 shows how the tutorial available in the library can be run. • Chapter 6 provides a conclusion and outlook.

Foundation API Client Library PHP – Installation Guide

2 Application Setup

The MDG Foundation API Client Library for PHP can be used for many kinds of projects in different contexts. This Usage Examples document will give you an understanding of how the library can be utilized. For a better understanding of the context, this chapter describes a typical usage scenario of the API. If you have already read the Installation Guide document, you should by now be familiar with the setup presented in this chapter. In that case you can safely skip this chapter and continue reading in chapter 4, “Sending an Example Request”.

2.1 Common setup of a PHP based application This section serves as an example and describes a common setup of the MDG APIs in a typical scenario. The architecture is as follows: A client on a desktop computer should be able to display financial data and use business logic available in the MDG platform. A webserver executes the PHP application, which authenticates itself against the MDG, collects the necessary financial data, issues API requests and delivers this data in form of dynamic HTML pages to the client. This architectural setup is depicted in the following illustration:

Please note, that the communication between the PHP application (located on the webserver) and the MDG Platform uses a proprietary communication protocol. This protocol is designed to be very efficient and thus uses a binary message exchange format. The protocol is called the Foundation PTL protocol. The easiest way to access the MDG platform from PHP applications without having to implement the full

Foundation API Client Library PHP – Installation Guide

Foundation PTL protocol stack (e.g., serialization and deserialization of binary PTL messages) is to use the client library provided by FactSet Digital Solutions. All required low-level messages are already implemented and encapsulated in easy to use PHP objects as provided by the library. This client library is called the MDG Foundation API Client Library for PHP (or PHP Extension Module). Amongst other things, this client library for PHP is used to:

• Perform the authentication handshake with the platform. • Submit any foundation request message • Provide a sophisticated caching layer to guarantee very low latency. Whereas clients could (in principle) request the MDG Foundation API on a low level protocol basis, the recommended way to connect to the MDG is via the provided PHP extension module, which then encapsulates the aforementioned core functionalities in a transparent way. The communication flow is as follows: The webserver retrieves the desired financial data from the platform and executes the PHP application which is using the provided PHP library. The library itself communicates with the MDG using PTL. Once received, the data is processed within the PHP application, which generates dynamic HTML pages. These HTML pages are then delivered to the requesting client device (either over HTTP or HTTPS). In this scenario there is no direct interaction between each individual client (i.e., browser) and the platform. The HTML pages are created in the PHP application and then forwarded to the client via the webserver.

3 Verification of the Installation

This document assumes that the Foundation API Client Library - PHP has previously been installed on your local environment. The next section “Integration into PHP server side code” explains how to establish a connection to the MDG. Establishing a connection is, of course, one of the first steps in accessing the MDG. In our case we also use it as a verification that the library is properly installed and working. If you have followed through the Installation Guide document (see references) and already have an established connection to the MDG, you might already know all of the following. In this case, you may safely skip this chapter and continue reading in chapter 4, “Sending an Example Request”.

3.1 Integration of Foundation API class files In order to facilitate the development the Foundation API Client Library for PHP provides PHP classes for every message specified in the Foundation API Message Protocol. Each of these PHP classes is available in a separate file. The library ships with extensive documentation on the individual PHP classes and the underlying API messages. This documentation can be found in your installation directory in /doc (e.g., access: /doc/ptl/foundation_ptl_index.html).

After the installation has completed the corresponding files are located in "/usr/share/php/MDGFoundationAPI". This directory should be linked into your project directory as follows:

Foundation API Client Library PHP – Installation Guide

Shell commands

3.2 Configuration of the __autoload() function To access the PHP files an "__autoload()" function is needed that takes care of including the library files automatically. This facilitates the handling of the class files as they themselves reference other class files and you otherwise would have to require all referenced class files in the correct order. Please integrate the provided PHP code (see below) at a central position in your application (normally in config files which are processed before bootstrapping).

PHP code

3.3 Connecting via the PHP extension module This section shows how to establish a connection to the MDG using the library. This is a typical step to verify the installation.

Step 1) Enter needed credentials Following parameters are needed to create a Frontgate connection.

• ID APPLICATION

• ID_USER

• HOST o host: frontgate.mdgms.com => stage = "production" o host: frontgate.show.mdgms.com => stage "show"

• PAYLOAD (always “foundation”)

• STAGE (has to be consistent with the HOST parameter)

Foundation API Client Library PHP – Installation Guide

o stage = "production" => host: frontgate.mdgms.com o stage "show" => host: frontgate.show.mdgms.com

• CREDENTIALS Store the credentials in a central configuration file. For Zend Framework the best place would be the application.ini PHP code

Step 2) Initiate a connection The previously defined parameters are now used to establish the connection. Initiate the connection at a central loading position of your application. You might as well integrate this code into an own library which is then included in your application.

PHP code

This demo code uses the isConnected() method to check that after these initialization steps a connection to the MDG API could be established. If this code does not throw an exception, the MDG Foundation API client library for PHP is configured properly and ready to use.

Foundation API Client Library PHP – Installation Guide

4 Sending an Example Request

After going through the previous chapters, the environment should be set up correctly and we are ready to utilizing the MDG via the MDG Foundation API Client Library for PHP. How this translates into sending requests to the MDG is demonstrated in this chapter.

4.1 Example Request to the “Echo” Endpoint from PHP Code The following sections present how to send requests to endpoints and how to receive and interpret their responses. In general, this involves three distinct steps, which are as follows: 1. Creating a request 2. Set request headers 3. Submit the request and retrieve/interpret the response Note that the following example code makes use of methods that assume this is run in the context of a class that extends the class "ExampleBase" from the example folder of the Foundation API Client Library tutorial.

Step 1) Set Helper Variables The following four variables configure your credentials and the debug level of the connection. All remaining code examples in this document rely that these variables are properly set and contain your valid credentials.

PHP code

Step 2) Create a Request (in this case POST-Request) A request to an endpoint is transported in a Foundation API message of type “MDGFoundationHighLevelRequest” (this corresponds to the class of the same name, which can be found in MDGFoundationHighLevelRequest.php). All requests to endpoints on the MDG are encapsulated in this message type.

Requests can be sent with either GET or POST transport methods. The example below uses the POST method, but an example for GET is also included in the tutorial section of the Client Library (see chapter 5). When compiling a request the version of the message needs to be set. In this case we are using VERSION_1_18. The version constants are also defined in the same class file

Foundation API Client Library PHP – Installation Guide

(MDGFoundationHighLevelRequest.php). Developers should always refer to the latest stable version containing an individual version number (in this case 1.18) and refrain from using the VERSION_LATEST constant, which is for maintenance reasons only.

PHP code

Step 3) Setting Header Information Details about the behavior of the request are set via header fields of the MDGFoundationHighLevelRequest. In order to keep this example easy to follow, we use viable default parameters in this case. If you like to configure your requests for your production environment please refer to the documentation of this request, which is available in your installation directory (/doc/ptl/foundation_ptl_index.html).

PHP code

Step 4) Setting Request Parameters The information which of the available endpoints in your customized API service is to be called and which parameters shall be passed to the corresponding endpoint need to be set as attributes to the MDGFoundationHighLevelRequest class as can be seen below.

PHP code

Foundation API Client Library PHP – Installation Guide

Note how in this example, the transfer mode is set to HTTP POST. The path to the endpoint is set with the “setPath” method. In this case the request is issued to a tutorial endpoint, which is identified by the following path attribute: /api/v1/tutorial/echo/post. When developing a real application a developer is likely to first log into the endpoint reference (see prerequisites), which provides him with a lot of details of his individual API. Within the endpoint reference the developer would locate the desired endpoint, read its documentation and find the necessary input parameters presented there. In the case of issuing POST requests (as in this example), the endpoint reference allows the developer to specify (and later copy & paste) a fully parameterized POST body. This POST body could be copied into the setValueFromString method and thereby completes the request specification.

Step 5) Submit the Request To submit the request, use the sendRequest method. Note that it returns a Job ID, which is a unique identifier for this request. PHP code

Step 6) Retrieve the Response In order to retrieve the response we need our previously obtained Job ID. In a particular installation Frontgate might be communicating a lot and in order to identify the response for your particular request you have to look out for your Job ID. For this scenario the receiveResponse function is used.

PHP code

Step 7) Output the Result The following code outputs the JSON result to the console. In an application, the result would be parsed for individual values of the contained attributes.

Foundation API Client Library PHP – Installation Guide

PHP code

4.2 Error Handling When errors occur in the processing of a request, the client receives a response of type “MDGFoundationErrorResponse”. Further details on the error are given inside the response message, so the contents of the message can be evaluated to find out what issue is encountered.

5 The PHP Client Library Tutorial

The previous chapter concludes the primary documentation about how to install and use the MDG Foundation API Client Library for PHP. As per now, the developer should be equipped to start developing his application, the PHP application is connected to Frontgate and can issue requests and receive responses. In order to help developers to learn more quickly on the capabilities of the MDG API, the Foundation API Client Library for PHP package is shipped with an included tutorial. This tutorial gives much more detail on how requests to Frontgate servers can be prepared, how they are sent to the servers and how the results can be interpreted. Developers which start using the MDG API are strongly encouraged to refer to the sample codes provided within this tutorial. The tutorial brings its own documentation, which is located in the /README file (the root folder of the API installation). The tutorial code is contained in several files, which are located in the /example folder.

5.1 Requests to Endpoints The tutorial covers a number of frequently used foundation requests. A detailed discussion on these requests is beyond the scope of this introduction. The remainder of this section focuses on requests that are related to the use of endpoints. Other requests are not covered in this document and should be accessed directly from the tutorial codes. The HighLevelRequest message (“MDGFoundationHighLevelRequest”) is used to obtain data from endpoints that are hosted on the Customized API Service for each project. Two example calls to different “echo” endpoints are available in the file “ExampleHighLevelRequest.php”. One of these endpoints has been used in the previous chapter.

Foundation API Client Library PHP – Installation Guide

The functionality of these “echo” endpoints is quite simple, but once the pattern how these endpoints are handled is understood, one can try out other endpoints by using a different path for the request. Again, please refer to the endpoint reference under https://endpointreference.mdgms.com/login to see the catalogue of endpoints available within your project. The HighLevelRequest message is likely to be the request that is used most of the time throughout a project. This is per design since endpoints are the main layer that abstract complex functionality on the MDG backend from the solutions.

5.2 Running the Client Library PHP Tutorial The following instructions assume that the library is installed on an environment that also has PHP installed. To run the tutorial code, a user must …

• access the example folder in the library’s installation directory • enter valid credentials into the “ExampleConnection.php” file, which stores the configuration data for the tutorial • run the example code with the Makefile that is provided • check the results and review the steps that are taken in the tutorial’s PHP files.

The following section shows how to do that on a Unix environment.

Step 1) Go to the folder where the library is installed Shell commands

$ ~/mdg_foundation_api-php$ cd MDGFoundationAPI-php71-1.12.0-1.x86_64/

Step 2) Locate the “example” folder in the library’s installation directory Check for the files and folders in the installation with “ls -l”: Shell commands

$ ~/mdg_foundation_api-php/MDGFoundationAPI-php71-1.12.0-1.x86_64$ ls -l total 56 drwxrwxr-x 2 john doe 4096 Okt 16 11:26 bin -r--r--r-- 1 john doe 15560 Okt 16 11:26 Changelog drwxrwxr-x 4 john doe 4096 Okt 16 11:26 doc drwxrwxr-x 2 john doe 4096 Okt 16 11:26 example drwxrwxr-x 3 john doe 4096 Okt 16 11:26 lib -rw-rw-r-- 1 john doe 13018 Okt 16 11:26 README drwxrwxr-x 2 john doe 4096 Okt 16 11:26 shared_lib -r--r--r-- 1 john doe 1374 Okt 16 11:26 UPDATING

Foundation API Client Library PHP – Installation Guide

Step 3) Go to the example folder Change to the /example folder. Shell commands

$ ~/mdg_foundation_api-php/MDGFoundationAPI-php71-1.12.0-1.x86_64$ cd example/ $ ~/mdg_foundation_api-php/MDGFoundationAPI-php71-1.12.0-1.x86_64/example

Step 4) Enter credentials into the “ExampleConnection.php” file Now, edit the ExampleConnection.php file, that contains a variable for the values $ID_APPLICATION and $CREDENTIALS. Note that some other variables can require changes as well. For the contents of HOST, STAGE and PAYLOAD, see chapter “Provide credentials”. In general it should be sufficient to change the variables, which are defined in the “Credentials and connection specification” block. Shell commands

$ vi ExampleConnection.php

In the current version of the PHP extension module these credentials need to be changed in the following code snippet of the ExampleConnection.php file (first column indicate the line numbers in this file):

68 #~~~~~~~~~~~~~~~~~~~~~ 69 # Credentials and connection specification 70 #~~~~~~~~~~~~~~~~~~~~~ 71 72 $ID_APPLICATION = '...INSERT YOUR APPLICATION...'; 73 $ID_USER = -1; // Default for NO_USER 74 $HOST = 'hosts:frontgate.show.mdgms.com:8200'; 75 $PAYLOAD = 'foundation'; 76 $STAGE = 'show'; 77 78 // syntax for application authentication: app: 79 // syntax for user authentication: user:: 80 // a colon in the username must be quoted with backslash 81 $AUTH = 'app:' . $ID_APPLICATION; 82 $CREDENTIALS = '...INSERT YOUR CREDENTIALS...';

Step 5) Run the Makefile Execute the Makefile that is provided in the example folder. Shell commands

$ ~/mdg_foundation_api-php/MDGFoundationAPI-php71-1.12.0-1.x86_64/example $ make

Foundation API Client Library PHP – Installation Guide

Step 6) Check the results When the tutorial classes are executed, some of the resulting data is output on the console. The degree of details depends on the parameter “debug” in the tutorial.php file. Since the tutorial contains a number of additional request, only a small part of the output is related to the MDGFoundationHighLevelRequest and its response. On the level “debug=1”, which is the default level, an example output for the execution of the MDGFoundationHighLevelRequest looks like this:

Shell output

*** Message: MDGFoundationHighLevelRequest (10039), dataset: default (0)

HighLevelResponse GET example body: {"data":{"text":"some-example- text","integer":42},"meta":{"status":{"code":200}}}

HighLevelResponse POST example body: {"data":{"text":"some post example text","integer":84}, "meta":{"status":{"code":200}}}

6 Conclusion and Outlook

This document ends Part II of the overview documentation of the MDG Foundation API Client Library for PHP. After going through this document, a reader should have an environment with a correctly set up library installation and an understanding how to interact with the MDG platform. The reader can now make further steps in applying the library to the use cases in concrete projects. Details on the endpoints that are available to a concrete project, and what the features of each endpoint accessible from such a project, can be found on the online documentation platform under https://endpointreference.mdgms.com/login.