Ruby & Rails notes of July

I'm working with GMO and NP payment APIs in July. My responsibility is writing wrappers for those APIs to use in our app. Here are some quick notes from things that I have learnt and applied:

Using YARDoc for creating documentation in Ruby

The code should comment for itself. It may be true to some extent however I find comments are neccessary when writing complex methods. A proper comment is great help in this case: explain method purpose, list of params and their descriptions, link to relevant code or documents, sample code, etc.

YARDoc is a great tool for this very purpose. It is used by Rubydoc to render documentations for various gems. YARDoc provides a guide for comments syntax & structure. The documentation then can be rendered by YARD gem and can be view on browser similar to what Rubydoc provides.

To run documentation server locally, inside project directory, run yard server. YARD will then automatically find all Ruby files insile directory and generate documentation from those files (if they are not yet parse).

To live preview any change, run yard server -r instead.

Here is a YARD cheatsheet for quickly syntax reference: https://gist.github.com/chetan/1827484

Mock API requests

Testing is a must for payment APIs. We could use test endpoints/accounts for testing purpose. However, using real connection to third party APIs even with test endpoints/accounts is not always the best choice:

  • Slow tests: real connections take time to establish
  • Random failure: Internet connection issues, remote servers do not respond, etc.
  • We may spam third party services when running tests again and again
  • Some params may be used only once (order_id) and will fail the second time you run the test.

So it is neccessary that we mock API requests and responses for testing. I find 3 tools for this purpose:

Mocky this is a web app that allows you to create a mock endpoint with custom requests/responses. The advantage of Mocky is that you do not have to use any external library. The down side is that you still use real connection for testing. Also it is a third party service with no guarantee about their existence. Information security may be a concern here too because anyone could access a mock endpoint you created if they happen to know its url.

Webmock this gem allows you to stub request with customize response to any url. By default it disables all external and local connections so beware when you use it for the first time.

VCR like its name, this gem works like a VCR: you first running a real request to a remote API, then VCR will record that request and from later on when running test, it will replay the record with the help of other tools like Webmock. This is the best tool so far for mimicking real API requests. Together VCR + Webmock are a great duo for API testing.

Working with SOAP

I don't see many services use SOAP these days. It is dying in favor of REST. Nonetheless, we may sometimes need to work with SOAP. I use the following 2 libs to work with SOAP in Ruby:

  • Savon: this is a SOAP client that helps handling SOAP requests and responses.
  • XML Builder: this gem has not been update for a long time but I find it good enough for building XML strings.

GMO payment methods

GMO accepts 5 methods of payment: one-time payment, split payment, bonus one-time payment, bonus split payment, ribo (revolving) payment.

It is pretty clear for one-time and split payment: one-time payment means you pay in full amount, at once. Split payment means you pay by different means (cash, cards, etc.) to fullfill the order total.

Revolving payment is also a common payment form in Western countries: for example you buy a PC for $1000 and you could pay the store $100 every month over 10 month period.

However bonus one-time payment and bonus split payment are confusing. What are they exactly? Apparently, Japanese companies often pay their employees bonus twice a year. This bonus is huge compare to regular monthly salary (its value is often between 1,5 - 3 months of salary). So many businesses provide an option for clients to defer their payment until they receive their bonus. This is a very interesting fact I've got to know recently.

Thanks to this blog post for its useful information about payment methods in Japan http://shiruba-japan.blogspot.com/2010/03/credit-cards-in-japan.html