Schematic
Generate Go client code for HTTP APIs described by JSON Hyper-Schemas.
Installation
Download and install:
$ go get -u github.com/interagent/schematic/cmd/schematic
Warning: schematic requires Go >= 1.7.
Client Generation
Run it against your schema:
$ schematic platform-api.json > heroku/heroku.go
This will generate a Go package named after your schema:
package heroku
...
Or using go generate
:
//go:generate schematic -o heroku/heroku.go platform-api.json
Client Usage
You then would be able to use the package as follow:
package main
import "./heroku"
func main() {
h := heroku.NewService(nil)
addons, err := h.AddonServiceList(nil)
if err != nil {
panic(err)
}
for _, addon := range addons {
fmt.Println(addon.Name)
}
}
A Service takes an optional http.Client
as argument. This Client will need to handle any HTTP-related details
unique to the target API service such as request authorization, request
header setup, error handling, response debugging, etc.
As an example, if your service use OAuth2 for authentication:
var config = &oauth.Config{
...
}
transport := &oauth.Transport{
Token: token,
Config: config,
Transport: http.DefaultTransport,
}
httpClient := transport.Client()
s := api.NewService(httpClient)
For an example of a service using HTTP Basic Auth, see the generated heroku-go client.
In general, creating a custom http.Transport
and creating a client from that is a common way to get an appropriate
http.Client
for your service.
Client Method Types
Methods on generated clients will follow one of a few common patterns corresponding to reading a single resource, reading a list of resources, and creating or updating a resource.
Reading a single resource looks like this, for example:
app, err := h.AppInfo("my-app")
if err != nil {
panic(err)
}
fmt.Println(app.Name)
fmt.Printf("%+v\n", app)
Where the struct app
is of a type e.g. heroku.App
defined in the
generated client. It will include generated struct members for the
various fields included in the API response.
Methods to read a list of resources look similar, for example:
apps, err := h.AppList(nil)
if err != nil {
panic(err)
}
for _, app := range apps {
fmt.Println(app.Name)
}
The first return value of these methods is a slice of domain structs
like heroku.App
described above.
List methods take a *ListRange
argument that can be used to specify
ordering and pagination range options on the underlying list call.
Methods to create or update look like this, for example:
newName := "my-app"
updateOpts := heroku.AppUpdateOpts{
Name: &newName,
}
app, err := h.AppUpdate("my-renamed-app", updateOpts)
if err != nil {
panic(err)
}
fmt.Println(app.Name)
Note the availability of generated types of with suffixes UpdateOpts
and CreateOpts
- these make it easy to generate arguments for update
and create calls. These types have pointer members instead of value
members so that you can omit some of them without defaulting them to
the a zero-value.
See the generated godocs for your package for details on the generated methods and types.
Development
Schematic bundles templated Go code into a Go source file via the templates package. To rebuild the Go source file after changing .tmpl files:
$ templates -s templates/ - templates/templates.go