Tag Archive for: SDK

Following on from our .Net & Java SDKs, we’ve now released our php SDK. This provides a friendly way to access Paydock, making it even easier to use Paydock.

 

You can pull this down through composer on Packagist

The code is open source on github.

Providing the right interface

One of the questions when putting together a new SDK is how to support this in a way that is as language friendly as possible. What we’ve put together for a strongly typed language like .Net, just doesn’t make as much sense for a dynamically typed language like php.

The simplest approach to this would be to simply map through the request, serialised as json, eg something like this:

1 $request = [“amount” => 100, “currency” => “AUD”, “token” => “token_id”]
2 $response = Charges::Create($request);

This works fine with simpler requests, but it tends to make it hard with larger, more complex request. In those cases, it’s easy to create a situation where you send through either too many parameters or too few. Also, when you can send through nested sets of parameters, it’s easy to send through parameters encoded at the wrong depth, e.g.:

1 // missing items object
2 $request = [“amount” => 100, “currency” => “AUD”, “token” => “token_id”, “transfer” => [“amount” => 25, “destination” => “account_id”]]
3 // correct structure
4 $request = [“amount” => 100, “currency” => “AUD”, “token” => “token_id”, “transfer” => [ “items” => [“amount” => 25, “destination” => “account_id”]]]

For this reason we settled on a fluent style interface.

Fluent interface

Using a fluent interface, you build up a request through a number of calls. Some good examples of fluent interfaces are things like LINQ in .Net:

1 var topOrders = orders.Where(o => o.Currency = “AUD”)
2 .OrderBy(o => o.Amount)
3 .Take(100)
4 .Select(o => o.Email);

These are often a very natural way of searching for data, but also work well to build up complex requests.

In order to make this as clear as possible, we’ve followed certain conventions. An example of this in the SDK is creating a charge with bank account details:

1 $response = $svc->create("John","Smith","[email protected]","+61414111111")
2 ->withBankAccount(self::bsbGateway, "test", "012003", "456456")
3 ->includeAddress("1 something st", "", "NSW", "Australia", "Sydney"2000")
4 ->call();

The first call is part of the call specifies the action (create). If this needs additional data, this is send through as with<Something>. Optional data is added through include<something>. And finally call() makes the actual call.

This made the API more complex to build, but provided a better experience of using the API.

As always, we’re open to improving this, so please raise any issues or concerns on on github and we’ll jump on it!

PayDock has now released Java SDK, which can be downloaded from JCentre. There are different dependency snippets to be inserted in your code based on your selected build settings (we support Gradle, Maven or Ivy).

The library is opened sourced and can be found here. Specific tests for you to reference in your program are here.

Planning

Writing the Java SDK was interesting and our approach changed over time. There were a few considerations

  1. Which HTTP library to use: I settled on HttpsURLConnection instead of Apache’s client. I found an example which worked early on so I didn’t change it.
  2. Which JSON library to use to map the data models: I settled on the GSON library from Google as it also handled the date format.
  3. How to deal with ever increasing API functionality while keeping the the code base similar: You will find I extend a few base classes to try maintain the peace.

IDE

I used Android Studio to write the PayDock Java SDK. As I was also planning to write an Android SDK, it only felt natural that I use this IDE to create the library. Creating Java libraries in this IDE are quite simple and it allowed me to use the same repository and build scripts that I would for the Android SDK. Having written a few projects in Android Studio in the past made me feel comfortable using it. From the one IDE, I had the ability to write the Java library, include the functionality tests, link into GitHub for source control and then upload the library to JCentre for distribution. In the project file, I had a simple app which referenced the remote Java library on JCentre. This allowed me to verify that the library worked as expected when downloaded from the repository.

Structure of the SDK

The SDK is split into three sections:

  • Models – contained the structure of the data to be sent and received.
  • Services – contained the methods exposed in the SDK, such as add charges.
  • Tools – contained helpful methods that the services used, such as the HTTP connection class and the query string to url class.

Using this format made it easy to add new endpoints and features as they were added to the API.

Publishing

I used some libraries which easily allowed me to upload the SDK to Jcentre via Bintray. Once some of the artifacts were set, all I had to do was change the library version every time I wanted to upload the library. After the initial set up it now only takes a few seconds to upload a new version of the library to JCentre.

You can use the following steps to upload the library to Bintray, assuming you have already set up an account with them:

  1. In local.properties of your project file set your bintray credentials
    bintray.apikey=<your api key here>
    bintray.user=<your user name>
  2. Add the correct scripts and the library artifacts in your build.gradle
    My build.gradle can be found here
  3. Run the following commands in the terminal
    ./gradlew build
    ./gradlew install
    ./gradlew bintrayUpload

Use the SDK

I put a link to the SDK earlier in the piece so you can download the SDK and I look forward to any reviews and comments. Happy coding!