Skip to content

Latest commit

 

History

History
265 lines (179 loc) · 10.3 KB

README.md

File metadata and controls

265 lines (179 loc) · 10.3 KB
Raw

tcmb_evds

A Rust crate for reaching the database of The Central Bank of The Republic of Turkey (CBRT).

Table of Contents

About

Name of the crate comes from Turkish meaning of the abbreviations of CBRT and the electronic data delivery system. Let's move on the contents. The crate is designed via main two structures and provides sync-async modes for various purposes.

Operational functions of the crate is based on EVDS web services. These services are divided into two parts in this crate. evds_basic and evds_currency are the mentioned parts. The latter provides all of the web services operations without adequate control mechanisms compared to the former in terms of currency operations. It can easily be understood that evds_currency provides access to currency operations. Furthermore, type and validity control is much obvious in this part. The evds_currency includes additional self-control algorithms, although it seems a little bit complicated according to evds_basic. These algorithms, checks syntax and validity of the given data. It is hard to get error with this structure.

In addition, the overall structure of the crate changes with respect to selected mode. Sync and async modes are recommended for sync and async programmings respectively. The mode selection can be made using feature adjustments.

The next contents include details of the two main structures, mode selection, examples and detailed explanations of the crate.

Install

Please, add appropriate one of the blow codes to your Cargo.toml to install the crate.

For async_mode, please add.

[dependencies]
tcmb_evds = "0.1"

For sync_mode, please add.

[dependencies]
tcmb_evds = {version = "0.1", default-features = false, features = ["sync_mode"]

Usage

evds_basic

An example of get_data getting series data.

    use tcmb_evds::*;
 

    // assigning required arguments.
    // another data series = "TP.DK.USD.A-TP.DK.USD.S-TP.DK.GBP.A-TP.DK.GBP.S"
    let data_series = "TP.DK.USD.A";

    let date = date::Date::from("13-12-2011")?;
    let date_preference = date::DatePreference::Single(date);

    let api_key = common::ApiKey::from("user_api_key".to_string())?;
    let return_format = common::ReturnFormat::Xml;
    let evds = common::Evds::from(api_key, return_format);


    // get data operation based on given series.
    let currency_data = evds_basic::get_data(data_series, &date_preference, &evds)?;

evds_currency

An example of get_data getting currency series data.

    use tcmb_evds::*;
 

    // common elements
    let api_key = common::ApiKey::from("user_api_key".to_string())?; 
    let return_format = common::ReturnFormat::Json;
    let evds = common::Evds::from(api_key, return_format);

    let date = date::Date::from("13-12-2011")?;
    let date_preference = date::DatePreference::Single(date);


    // currency series creation
    let exchange_type = evds_currency::ExchangeType::new();
 
    let currency_code = evds_currency::CurrencyCode::Usd;
 
    // Ytl mode adds "YTL" to currency series, when it is true.
    let ytl_mode = true;
   
    let currency_series = 
        evds_currency::CurrencySeries::from(
            exchange_type, 
            currency_code, 
            date_preference, 
            ytl_mode
        );
 
 
    // get data operation based on created CurrencySeries.
    let currency_data = currency_series.get_data(&evds)?;

Details

There are some details to clarify users' knowledge of how to use this tcmb_evds API library.

evds_basic

This part is the one of the two fundamental parts users face with. The most EVDS web service operations can be done with using evds_basic API functions. These functions are get_data, get_data_group, get_categories, get_advanced_data_group and get_series_list. The functionalities of these functions are explained lucidly in the documentation of the project. At the same time, users can learn more about these functions below. The Function Names and Web Services as Functions parts give extra information about these functions.

Functions of evds_basic uses some structures given below in supporting structures which are date::DatePreference and common::Evds that check whether the given data is valid or not when they are created. These supporters meet the requirement of common information that EVDS need as standard. So, the given data by users are checked and automatically converted to convenient urls with these supporters. However, there are some parameters, the mentioned functions requires for specific EVDS operations. These parameters are directly used in last url format for web service requesting. That means there is no data validity checking for these parameters. Therefore, user becomes responsible to supply valid data for mentioned parameters.

evds_currency

This is the other part of the two fundamental parts users face with. The specific currency operations can be done with using evds_currency API functions. These functions are get_data, get_advanced_data and get_multiple_data. These functions are methods of CurrencySeries and MultipleCurrencySeries structures. How to use details of these functions are explained lucidly in the documentation of the project. At the same time, users can learn more about these functions below. The Function Names and Web Services as Functions parts give extra information about these functions.

Mentioned methods require some structures that are divided into two. These are main and supporting structures. The formers are called CurrencySeries and MultipleCurrencySeries. These structures implements the mentioned methods that are the main operation functions and contains important sub-structures explained in the crate documentation. The latter structures are called common::Evds and AdvancedProcesses. The first one supply common information that EVDS need as standard. The other one gives users more customization option to get specific currency data.

The mentioned 3 methods use pre-created structures. When these structures are created, this crate checks validity and correctness of the given data. Therefore, usage of evds_currency methods are error free methods unlike evds_basic. Namely, evds_currency is responsible for checking the validity of the giving data.

Function Names

The evds_basic API functions given in this crate:

  • get_data returns data about requested data series.

  • get_data_group returns requested data group.

  • get_categories returns all requested categories of EVDS.

  • get_advanced_data_group returns specified data groups.

  • get_series_list returns all usable series list.

The evds_currency API functions given in this crate:

  • get_data returns data about just one currency.

  • get_advanced_data returns data about just one currency with frequency

  • formulas.

  • get_multiple_data returns data about more than one currency.

Supporting Structures

Common: Fundamental structures used in user API functions for both evds_basic and evds_currency.

  • DatePreference: Most of the functions requires.
  • Evds: Every function requires.

For evds_basic

  • DatePreference

For evds_currency

  • AdvancedProcesses: Includes advanced currency data configurations for get_advanced_data function.

  • Currency Series: A composite structure containing below structures to supply single and advanced (configured) currency data.

    • ytl_mode: This is a bool option to choose currency value wrt YTL revolution.
    • ExchangeType: This is a structure to determine currency value is selling/buying.
    • CurrencyCode: An enum of currency unit option.
    • DatePreference: Fundamental common structure.

  • MultipleCurrencySeries: A composite structure containing below structures to supply multiple currencies data.

    • ytl_mode
    • ExchangeType
    • CurrencyCodes: A structure of currency unit options.
    • DatePreference

Web Services as Functions

The web services, described in user guide and kullanim kilavuzu in Turkish, correspond to following functions.

Format:

'function_sign' corresponds to 'a section of user guide'

evds_basic functions:

  • get_data corresponds to 1. EVDS Series Data Services & 2.1. Level Values Requests
  • get_data_group corresponds to 3. All Series Data By Given Data Group
  • get_categories corresponds to 4.1. Category Service
  • get_advanced_data_group corresponds to 4.2.Data Group Service
  • get_series_list corresponds to 4.3. Series Service

evds_currency methods:

  • get_data corresponds to 1. EVDS Series Data Services
  • get_advanced_data corresponds to 2.2. ... series with frequecy formulas
  • get_multiple_data corresponds to 2.1. Level Values Requests

Comparison

This section illustrates the fundamental differences of the two main structures.

  • evds_basic

    • Provides most of the EVDS web service operations except currency value with frequency formulas service which is called advanced currency operations in this crate.
    • Users are responsible for ensuring validity of the given series and some data.
    • Less reliable for the currency service operations.

  • evds_currency

    • Specified for operating currency operations.
    • Given series and some data are automatically checked.
    • More reliable for the currency service operations.

More

Detailed examples of usage and more are given in the documentation of the crate. User can visit crates.io or clone the repository and just enter Cargo doc --open command into the terminal.

References