The api can be accessed by through

• REST: http://zimrate.tyganeutronics.com/api/v1
• Graphql: http://zimrate.tyganeutronics.com/api/graphql

Accessing Rates

There are a total of four possible query parameter combinations (GET | POST) that can be passed to get data from both the RESTful and Graphql Api namely:

search

- Allows you to get currency rates using only part of a name of said currency

currency

- Can only be either of ZAR, BOND, OMIR, RBZ, RTGS, this is only for when you require a specific currency.

date

- When provided only matching rate after this date will be returned. Accepts common date formats, though a unix time stamp is preferred.

prefer

- Can only be either of MAX, MEAN, MEDIAN, MIN, MODE, RANDOM or empty to return the whole list.

All these parameters are optional and are there only as a convenience to get the specific data that you need.

Javascript CORS (Cross Origin Resource Sharing)

By default the api does not allow CORS but in cases where you require it there are two options:

• Adding cors=true to your request

• Or using the script tag with the url having the parameter callback where the value will be the name of the function you want called after the tag is loaded. For example callback=myFunction will return wrapped in a function call as myFunction({...});

  function getRates() {
      var s = document.createElement("script");
      s.src = "http://zimrate.tyganeutronics.com/api/v1?callback=myFunction";
      document.body.appendChild(s);
  }
  
  function myFunction(rates) {
      console.log(rates);
      //remove script tag...
  }

Both achieve the same result with the later being applicable whilst the document is still loading.

Graphql

Unlike REST, graphql allows you to structure the responses however you like, even reducing the number of requests made to the server in one go.

{
    USD : rate(prefer : RANDOM, cors: true ) {
        currency
        last_checked
        last_updated
        rate
    }, 
    info: info
}

Using a Graphql schema browser is highly recommended to fully explore the api. You may use the example as a starting point as the possibilities of graphql are beyond the scope of this documentation.

...

• Avoid accessing returned values based on their position as if a site goes down or is removed that site's rates may not be included thus distorting their position. A request with the prefer parameter is much more relaible as it includes values from all available sites and not a specific one.
• You can disable info from the response by passing info=false in your request.

Disclaimer:

As a developer, I guess your are familier with how we (as software developers) hate to write documentation for software. After all we are not bloggers. But I have tried to be as extensive as possible, please contact me if all this does not make sense after reading through a few times.