The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Finance-Currency-FiatX-0.011
River stage one • 3 direct dependents • 3 total dependents
++
/ Finance::Currency::FiatX::Role::Source

NAME

Finance::Currency::FiatX::Role::Source - Role for FiatX sources

VERSION

This document describes version 0.011 of Finance::Currency::FiatX::Role::Source (from Perl distribution Finance-Currency-FiatX), released on 2019-01-10.

DESCRIPTION

All routines must return enveloped result.

 [$status, $reason, $payload, \%extra]

This result is analogous to an HTTP response; in fact $status mostly uses HTTP response codes. $reason is analogous to HTTP status message. $payload is the actual content (optional if $status is error status). %extra is optional and analogous to HTTP response headers to specify flags or attributes or other metadata.

Some examples of enveloped result:

 [200, "OK", 14000]
 [404, "Not found"]

For more details about enveloped result, see Rinci::function.

REQUIRED ROUTINES

get_all_spot_rates

Usage:

 get_all_spot_rates() -> [$status, $reason, $payload [ , \%extra ] ]

Return spot rates for all currency pairs and all rate types available from this source. If the source provides a way to list all supported rates in a single API call or webpage, then this routine should return them. Otherwise, this routine should return status 501, e.g.

 [501, "Source does not offer a way to list all spot rates at once"]

Result payload is an array of hashes, where each hash must contain these keys: pair (str in the format of <from_currency>/<to_currency>, e.g. USD/IDR), rate (num, the rate), mtime (Unix epoch, last updated time for the rate, according to the source). type ("buy" or "sell" or "buy_XXX" or "sell_XXX" where XXX is some type of rate, e.g. "buy_er" for e-Rate buy rate, or "sell_bn" or bank note sell rate. At the very least, "buy" and "sell" should be supported; if the source has different types of buy-sell rates, one should be picked as the default "buy" and "sell"). Hash can also contain these optional keys: note (str).

get_spot_rate

Return spot (the latest) rate for a currency pair and a specific rate type.

Usage:

 get_spot_rate(%args) -> [$status, $reason, $payload [ , \%extra ] ]

Example:

 get_spot_rate(from => "USD", to => "IDR", type => "sell");
 # => [200, "OK", {rate=>14100, mtime=>1530075306, }]

Arguments:

  • from

    Required. Currency code.

  • to

    Required. Currency code.

  • type

    Required. String. Either "buy" or "sell" or "buy_XXX" or "sell_XXX" (see "get_all_spot_rates" for more details.

If a source does not support the currency pair, routine must return status 501. If the curerncy pair is supported but the type is unknown, routine must also return status 501.

Result payload is hash that must contain these keys: pair (str in the format of <from_currency>/<to_currency>, e.g. USD/IDR), rate (num, the rate), mtime (Unix epoch, last updated time for the rate, according to the source). type ("buy" or "sell" or "buy_XXX" or "sell_XXX"). Hash can also contain these optional keys: note.

TODO: get_historical_rates

Usage:

 get_historical_rates(%args) -> [$status, $reason, $payload [ , \%extra ] ]

Arguments:

  • from

    Required. Currency code.

  • to

    Required. Currency code.

  • from_date

    Required. Date as Unix epoch (UTC).

  • to_date

    Required. Date as Unix epoch (UTC).

  • frequency

    Required. String. Either "daily" or "weekly" etc.

If source does not support historical rates, routine must return status 501 response, e.g.:

 [501, "Source does not offer historical rates"]

BUGS

Please report all bug reports or feature requests to mailto:stevenharyanto@gmail.com.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019, 2018 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.