Day 7 - Writing documentation and making libraries

Published by Michael Banzon on Sun Feb 19, 2017

This part is all about wrapping the service up and making at available - we’ll write some documentation and provide a Javascript library to do the currency conversion.

This is day seven of our full week of going full stack with one single project.

If you haven’t already I really recommend reading the day zero kick off post and going from there - it will make a lot more sense.

Writing the documentaion

We are going to define some simple documentation of the endpoints on the server.

For this purpose we use a simple template and this is the bare minimum of documentation - sometimes this is enough - for simple services like the one we are making - but often it won’t be. Sometimes more context etc. is needed to understand the service and everything about the data going back and forth.

A change to the server repository added the documenation. Making the documentation available in the GitHub repository along with the code - as markdown - has the advantage that GitHub will show it nicely rendered in the webinterface.

Making a library!

So we’ve added some documentation on how to use the library. It’s fine. But let’s add something more awesome!

Let’s add an endpoint to the server that can be included on a website as a Javascript library! Like this:

<script type="text/javascript" src="$SERVER/js?base=DKK"></script>

The idea is that this endpoint will return a script that’ll set itself up to perform currency conversion stuff for the user in the UI without a trip back and forth between the frontend and backend when conversion is needed.

The changes made to the server is in this commit. The script generator is made using the standard text/template package and the template is parsed on every request - this could be optimized (which is quite trivial).

When included on a web page the script returns a script similar to this:

(function() {
	var currency = {
		currencies: ['HRK', 'INR', 'TRY', 'AUD', 'CNY', 'HKD', 'KRW', 'NZD', 'HUF', 'CHF', 'MXN', 'PHP', 'JPY', 'GBP', 'USD', 'RON', 'SEK', 'THB', 'BRL', 'CAD', 'ILS', 'SGD', 'EUR', 'CZK', 'PLN', 'NOK', 'RUB', 'IDR', 'ZAR', 'BGN', 'DKK', 'MYR', ],

		rates: {
			'HRK': 1.0010224123550462,
			'INR': 9.613568488174995,
			'TRY': 0.5262329485834208,
			'AUD': 0.18688621626711868,
			'CNY': 0.9838566470255872,
			'HKD': 1.1119945112599887,
			'KRW': 164.76444157451502,
			'NZD': 0.19922242849839913,
			'HUF': 41.477654908924585,
			'CHF': 0.143097371324024,
			'MXN': 2.9333817633922568,
			'PHP': 7.171550030941426,
			'JPY': 16.15411520972906,
			'GBP': 0.11531735141388866,
			'USD': 0.14327225764791346,
			'RON': 0.6083757096348913,
			'SEK': 1.2709930852638094,
			'THB': 5.013856377969705,
			'CAD': 0.18738396965049642,
			'ILS': 0.5309817849167272,
			'SGD': 0.2029488524766594,
			'EUR': 0.13452794145343988,
			'CZK': 3.6350795060133994,
			'PLN': 0.5825732504641213,
			'NOK': 1.1925229370140178,
			'RUB': 8.336266042457018,
			'IDR': 1910.1770387709528,
			'ZAR': 1.8747410337127022,
			'BGN': 0.2631097478946377,
			'DKK': 1,
			'MYR': 0.6379853095487933,
		},

		convert: function(amount, target) {
			return this.rates[target] * amount
		}
	}

	window.currency = currency
})();

It sets a global (on window) variable currency that has the .currencies-array with names (shortened) of all the known currencies. This can be used to loop through in the UI to provide a list eg. - and it has the .convert(amount, target)-function that converts an amount from the base currency to the given target currency.

A script like this is simple but provide the basic building blocks for building an application with currency conversion in the UI.

With the CI/CD stuff we implemented on day five and the monitoring we set up on day six we’ll get these changes live when we push to the GitHub repository and we can be confident that the server is still running and performing.

Conclusion

This is it!

This final seventh post is the conclusion of a full week of going full stack with one single project!

Thank you for reading along!