api Archives - Andrei Avram

Abstraction for better APIs

One problem with the iterator used in the static polymorphism article is the lack of abstraction. The storage container is a tuple and the caller is required to explicitly handle it: create it and pass it to the iterator.

This is not ideal because the iterator exposes internal implementation details and its public interface is coupled to those details. A change of the storage container would break the API and the caller would be required to make changes to their code.

Perhaps the tuple could be switched to an array that uses a variant from boost or C++17 standard library. The implementation change should not impact the public API.

This can be achieved by designing an abstract API that does not expose the internal storage. I’m going to present a way of doing this by wrapping the old static iterator (I’ve changed it a little bit; the entire code is at the end of the article) with a new class that will be the public API.

The API accepts a list of types that you want to iterate over by variadic template arguments.

    template <typename... Ts>
    class StaticIterator {
        static_assert(sizeof...(Ts) > 0, "at least one type is required");
    };

Continue reading Abstraction for better APIs

The mid-language crisis

A while after I wrote the Apixu libraries for Go and PHP, they asked me if I could help them with some issue a client had when trying to install the Python library. I quickly tested and sent them steps on how to install all requirements. And I noticed the library could use some additions.

My experience with Python was of a few lines and I felt like it would be a good context to write a few more, to understand the language a little better, to learn about its requirements, ways to set up a library and write some tests to validate JSON schemas. A clean language with a simple package manager and clear error handling. Basic integrations with Flask and Django were pretty smooth.

One thing I like about Apixu is they have multiple libraries and after freshening the Python one I was inspired to do more. And there was where to choose from.

JavaScript is an old friend but we met only in the browser some years ago. It was time to face its server side of the moon and add some touches to the NodeJS library. I’m not a huge fan of callbacks, but Promises are indeed a nice way to handle responses. Express was easy to start with, I like its micro framework feeling. The package manager, npm, doesn’t seem too far from PHP’s composer, we got along well. Continue reading The mid-language crisis

Apixu Go: A Golang package for Apixu weather service

Not long ago I’ve mentioned Apixu in a post about handling errors. I found out about this service on DevForum, a development discussions platform I visit daily. What I like the most about Apixu is that they have various language libraries for consuming their API. Not great libraries and not all of them are complete, but they try to offer as many variations as they can for their service.

I noticed they were missing a Go library and I was missing an idea to learn new things on. And I just started writing the code until it got to a full package that covers all API methods with error handling, both JSON and XML formats, unit tested, versioned.

It has a simple interface that clearly defines the API methods with their input parameters and responses. And it can be extended for custom needs.

Some important things I learned from the process are simplicity, segregation and isolation, specific errors, memory management, and creating custom marshalers.

Check it out on Github. See documentation for the package and for the API.

In the end, they adopted my package among their official ones.

Handling API errors

The past days I’ve practiced Go by writing a package for Apixu weather service. They have a a straightforward REST service to offer their weather information.

Their service also returns an error response if it can’t offer data based on your needs, if you use an invalid API key, or for other cases. Of course, the Go package should also return errors if the case.

No problem with returning data, but I had some issues handling errors. There can be general errors that have nothing to do with Apixu (but with the package internals) and errors returned by them. My first approach was to return three values for each API method:

Search(q string) (Search, ApixuError, error)

But it smelled right away. There had to be another way. Continue reading Handling API errors

Using data structures for types

Data types should be very specific. Anyone using a variable should know exactly what type it is, how it looks like (if it’s a structure). While for some languages it’s common sense and really enforced, others will let you mess with a variable’s type, no matter it’s a primitive, an object, an array.

I’m going to talk about data coming from JSON, databases or other sources, which can be represented into data structures.

In a language like Go, you map data into well defined structures.

package main

import (
    "encoding/json"
    "fmt"
)

type Person struct {
    ID int
    Age int
    Name string
}

func main() {
    string := `{
        "id":453,
        "age":26,
        "name":"John Doe"
    }`

    input := []byte(string)

    person := Person{}
    err := json.Unmarshal(input, &person)
    if err != nil {
        panic(err)
    }

    fmt.Println(person) // Person struct
    fmt.Println(person.ID) // integer
    fmt.Println(person.Age) // integer
    fmt.Println(person.Name) // string
}

You know exactly that you have an object of type Person, with integer ID, integer Age, and string Name. No need to check anything anywhere. If you mess up, you’ll know at compile time.

A dynamic typed language like PHP has a different approach. Continue reading Using data structures for types