dinero

README

dinero

dinero is a Go client library for accessing the Open Exchange Rates API (https://docs.openexchangerates.org/docs/).

Upon request of forex rates these will be cached (in-memory), keyed by base currency. With a two hour expiry window, subsequent requests will use cached data or fetch fresh data accordingly.

Installation

go get -u github.com/mattevans/dinero

Usage

Get All

// Init dinero client.
client := NewClient(os.Getenv("OPEN_EXCHANGE_APP_ID"))

// Set a base currency to work with.
client.Rates.SetBaseCurrency("AUD")

// Get latest forex rates using AUD as a base currency.
response, err := client.Rates.All()
if err != nil {
  return err
}

{
   "rates":{
      "AED":2.702388,
      "AFN":48.893275,
      "ALL":95.142814,
      "AMD":356.88691,
      ...
   },
   "updated_at":"2016-12-16T11:25:47.38290048+13:00",
   "base":"AUD"
}

---

Get Single

// Init dinero client.
client := NewClient(os.Getenv("OPEN_EXCHANGE_APP_ID"))

// Set a base currency to work with.
client.Rates.SetBaseCurrency("AUD")

// Get latest forex rate for NZD using AUD as a base currency.
response, err := client.Rates.Single("NZD")
if err != nil {
  return err
}

1.045545

---

Expire in-memory cache

The following will expire the in-memory cache for the set base currency.

client.Cache.Expire()

Contributing

If you've found a bug or would like to contribute, please create an issue here on GitHub, or better yet fork the project and submit a pull request!

Documentation

Index

• func CheckResponse(r *http.Response) error
• type CacheService
  • func (s *CacheService) Expire(base string)
  • func (s *CacheService) Get(base string) *RatesStore
  • func (s *CacheService) IsExpired(base string) bool
  • func (s *CacheService) Store(base string, rates map[string]decimal.Decimal)
• type Client
  • func NewClient(oxrAppID string) *Client
  • func (c *Client) Do(req *http.Request, v interface{}) (*Response, error)
  • func (c *Client) NewRequest(method, urlPath string, body interface{}) (*http.Request, error)
• type ErrorResponse
  • func (r *ErrorResponse) Error() string
• type RatesService
  • func (s *RatesService) All() (*RatesStore, error)
  • func (s *RatesService) GetBaseCurrency() string
  • func (s *RatesService) SetBaseCurrency(base string)
  • func (s *RatesService) Single(code string) (*decimal.Decimal, error)
• type RatesStore
• type Response
• type UpdateResponse
• type UpdateService
  • func (s *UpdateService) LatestRates(base string) error

Functions

func CheckResponse

func CheckResponse(r *http.Response) error

CheckResponse checks the API response for errors. A response is considered an error if it has a status code outside the 200 range. API error responses map to ErrorResponse.

Types

type CacheService

type CacheService service

CacheService handles in-memory caching of our exchange rates.

func (*CacheService) Expire

func (s *CacheService) Expire(base string)

Expire will expire the cache for a given base currency.

func (*CacheService) Get

func (s *CacheService) Get(base string) *RatesStore

Get will return our stored in-memory forex rates, if we have them.

func (*CacheService) IsExpired

func (s *CacheService) IsExpired(base string) bool

IsExpired checks if we have stored cache and that it isn't expired.

func (*CacheService) Store

func (s *CacheService) Store(base string, rates map[string]decimal.Decimal)

Store will save our forex rates to a RatesStore.

type Client

type Client struct {
	AppID      string
	UserAgent  string
	BackendURL *url.URL

	// Services used for communicating with the API.
	Rates  *RatesService
	Update *UpdateService
	Cache  *CacheService
	// contains filtered or unexported fields
}

Client holds a connection to the OXR API.

func NewClient

func NewClient(oxrAppID string) *Client

NewClient creates a new Client with the appropriate connection details and services used for communicating with the API.

func (*Client) Do

func (c *Client) Do(req *http.Request, v interface{}) (*Response, error)

Do sends an API request and returns the API response. The API response is JSON decoded and stored in 'v', or returned as an error if an API (if found).

func (*Client) NewRequest

func (c *Client) NewRequest(method, urlPath string, body interface{}) (*http.Request, error)

NewRequest creates an API request. A relative URL can be provided in urlPath, which will be resolved to the BackendURL of the Client.

type ErrorResponse

type ErrorResponse struct {
	*http.Response
	ErrorCode   int64  `json:"status"`
	Message     string `json:"message"`
	Description string `json:"description"`
}

An ErrorResponse reports the error caused by an API request

func (*ErrorResponse) Error

func (r *ErrorResponse) Error() string

type RatesService

type RatesService service

RatesService handles retrieving forex rates for a given currency, either from in-memory cache or by fetching fresh results.

func (*RatesService) All

func (s *RatesService) All() (*RatesStore, error)

All will build and execute request to fetch the latest rates for given base currency either from the in-memory cache or OXR API.

func (*RatesService) GetBaseCurrency

func (s *RatesService) GetBaseCurrency() string

GetBaseCurrency will return the baseCurrency.

func (*RatesService) SetBaseCurrency

func (s *RatesService) SetBaseCurrency(base string)

SetBaseCurrency will set the base currency to be used for requests.

func (*RatesService) Single

func (s *RatesService) Single(code string) (*decimal.Decimal, error)

Single will return forex rate for given base/code.

type RatesStore

type RatesStore struct {
	Rates     map[string]decimal.Decimal `json:"rates"`
	UpdatedAt *time.Time                 `json:"updated_at"`
	Base      string                     `json:"base"`
}

RatesStore holds our forex rates for a given base currency

type Response

type Response struct {
	*http.Response
	ErrorCode int64
	Message   string
}

Response is a OXR response. This wraps the standard http.Response returned from the OXR API.

type UpdateResponse

type UpdateResponse struct {
	Timestamp int64
	UpdatedAt time.Time
	Base      string
	Rates     map[string]decimal.Decimal
}

UpdateResponse is the set of parameters that is used in response to a send request

type UpdateService

type UpdateService service

UpdateService handles communication with /latest.json methods of the https://docs.openexchangerates.org/docs/latest-json

func (*UpdateService) LatestRates

func (s *UpdateService) LatestRates(base string) error

LatestRates will build and execute request to /latest.json using the base currency provided.