Experience (with feedback) on Go SDK for Koyeb API

General
1

I documented my experience Navigating Koyeb’s Golang SDK.

I’d used the SDK previously to write a Prometheus Exporter of Koyeb resources but, this time I wanted to be able to create Services (Apps|Deployments).

The SDK (koyeb-api-client-go) is comprehensive but machine-generated and idiosyncratic.

The documentation is very good with both the default pkgsite documentation and Documentation for API Endpoints which includes sample code.

The SDK provides multiple ways to achieve the same goal, e.g.:

apiCreateApp := koyeb.NewCreateApp()
apiCreateApp.SetName(name)

And:

name := "foo"
apiCreateApp := koyeb.CreateApp{
	Name: &name,
}

The SDK provides excellent error handling:

  • source type is required (definition.source)
  • min and max need to be equal (definition.scalings.0.max)
  • cannot be blank (definition.scalings.0.min)
  • at least one scaling configuration is required (definition.scalings)
  • must be a valid value (definition.ports.0.protocol)
  • only http and http2 ports can be exposed publicly (definition.routes.0.port)
  • must be no greater than 10 (definition.health_checks.0.restart_limit)
  • rpc error: code = NotFound desc = not_found (definition.instance_types.0.scopes.was)
  • rpc error: code = NotFound desc = not_found (definition.instance_types.0.scopes.WAS)
  • rpc error: code = NotFound desc = not_found (definition.regions.0)

However, I was unable to find documentation for this validation (in the API or the Golang docs) and the errors only occur in failing API call response messages.

Some of the missing documentation e…g.: DeploymentEnv, DeploymentInstanceType, DeploymentScaling Scopes required me to manually deploy a Service so that I could GET it using the API in order to understand what values were being used. It appears that Scopes are of the form region:{region} and I had to make the list the regions using the API in order to realize that the UI’s value of e.g. WAS is actually was for the API.

There’s more detail in my post.

I’m hoping this is received, as intended, as constructive feedback on a mostly very good SDK and to help others navigate it too.

2 Likes
2

Thank you so much for the great feedback @Daz_Wilkin !

We will take a look and work on improving the documentation of errors.

1 Like