nesv.ca

[ANN] go-dynect

This post is the first announcement of my DynECT client library for Go.

Link for the lazy: github.com/go-dynect/dynect.

This library is extremely simple and does nothing more than provide data structures, and authentication handling for the DynECT REST API. You should keep that link handy, as unlike most client libraries you will find, API endpoints are not mapped to functions of any sort; this will be explained further down.

The source for the library is on GitHub.

Installing the library

The library can be simply installed by running:

$ go get -u github.com/nesv/go-dynect/dynect

Breaking convention

I come from the Python world, where client libraries are usually classes upon classes, with API features mapped to class and instance methods. Even though Go allows you to pin methods to types, I find this approach tiresome, and in the end, the onus is on me — the developer of the library — to make sure the API-to-method mappings stay up-to-date.

The approach I have taken with go-dynect/dynect is slightly different. In this package, I am giving you:

  • Structs to hold the data returned by DynECT’s API
  • Convenience methods for authenticating with the API
  • A single method — *Client.Do() — for making API calls
  • Automatic response data-to-struct unmarshaling (and vice versa)

I have been trying to take this approach with more and more client libraries that I write, but it doesn’t always apply. What this approach means for you, the developer:

  • You have to keep a reference of the API provider’s endpoints handy
  • You have to know what kind of data to expect from calling the API

If you consider these impositions unfair, then you are free to implement your own client libraries that abstract the API to the extent that if something goes wrong (maybe because DynECT’s API changed), the users will have no idea as to what is wrong.

My rationale with this approach is that I want to provide you, the user of this library, with something that is as out-of-the-way as possible; I do not want you having to learn the API for my library, as well as the service’s upstream API. I am hoping, that by this take on things, you will only have to learn DynECT’S API, and my library will only serve as a bridge for your communications.

Examples!

Alright, here are the basics of using this library:

  • Create a client
  • Log in
  • Make requests
  • Log out

The Make requests point is really the only one that requires any sort of explanation here:

All requests to the API are done through the *Client.Do() method.

To the *Client.Do() method, you provide four arguments:

  1. The HTTP verb as a string (“GET”, “PUT”, “POST”, “DELETE”, etc.)
  2. The API endpoint as a string (without the /REST/ prefix)
  3. Request data that can be marshaled to JSON, or nil
  4. An interface{} to unmarshal the response data to, or nil

Here is a quick example of calling this method:

client := dynect.NewClient(...)

...

var zones ZonesResponse
err := client.Do("GET", "Zone", nil, &zones)
if err != nil {
	...
}

Fairly straight-forware, n’est-ce pas?

Here is a more-complete example where we create a new client, log in, make a request to get all of the zones we have setup, a second request to get all of the records in each zone, and then we print each record out:

In closing…

As always, if you feel the need to holler at me, you can hit me up on Twitter, Google+, or just flat-out send me an email. Also, if there are any issues with code snippets, or spelling errors, please do not hesitate to create an issue on GitHub, or send me a pull request.

Hack the planet!