vectorsurv-go

A Go client library for the VectorSurv API. It covers the full published API surface: every resource's list/get/create/update operations, read-only reference lookups, and the action endpoints (validation, pool/collection linking, calculations, label generation, and more).

The library is generated from the VectorSurv OpenAPI specification by the generator in gen/ (go run ./gen), so it tracks the published API closely.

Authentication

The library authenticates with a VectorSurv Gateway username and password taken from environment variables:

export VECTORSURV_USERNAME=your_gateway_username
export VECTORSURV_PASSWORD=your_gateway_password

Authentication uses the API's /login endpoint and caches the returned bearer token, refreshing it automatically when it expires (tokens are valid for one hour). If the server ever rejects a cached token with 401, the library refreshes the token once and retries the request.

Library usage

import (
    "context"
    "source.gleipnir.technology/Gleipnir/vectorsurv-go"
)

ctx := context.Background()
client, err := vectorsurv.NewClient()
if err != nil {
    return err
}

// List records.
sites, err := client.ListSites(ctx)               // []Site
cols, err := client.ListCollections(ctx)          // []Collection
agencies, err := client.ListAgencies(ctx)         // []Agency

// Fetch a single record by ID.
col, err := client.GetCollection(ctx, 12345)      // *Collection
site, err := client.GetSite(ctx, 67890)           // *Site

// Create a record. The request body type is <Type>Input (or <Type> when the
// create body matches the record shape).
newApp := &vectorsurv.ApplicationInput{}
agency := 3
newApp.Agency = &agency
newApp.Local = "NEW"
app, err := client.CreateApplication(ctx, newApp) // *Application

// Update a record. id selects the row; the body type is <Type>Input or a
// dedicated <Type>Input2 when the PUT body differs from the POST body.
updated, err := client.UpdateApplication(ctx, 42, &vectorsurv.ApplicationInput2{...})

// Delete (deactivate) a record.
err = client.DeleteApplication(ctx, 42)

// Nested resources take their parent's key first.
abundance, err := client.ListAbundances(ctx, 12345)          // collections 12345
one, err := client.GetAbundance(ctx, 12345, 7)               // abundance 7 in collection 12345

Request body types

Every resource that supports create/update has a matching input type so you don't send server-managed fields (ids, timestamps, add_date, …) on writes:

• CreateX(ctx, in *XInput) — POST body derived from the endpoint's request schema.
• UpdateX(ctx, id, in *XInput) — PUT body. When the PUT schema differs from the POST schema a separate XInput2 (or similar) is generated.

When a resource's create/update body is identical to its record shape, the *X type itself is used instead of an XInput.

Reference lookups

Many read-only reference tables are exposed as List/Get methods, e.g.:

lures, err := client.ListLures(ctx)         // []Lure
trap, err := client.GetTrap(ctx, 5)         // *Trap
species, err := client.ListSpecies(ctx)     // []Species
targets, err := client.ListTestTargets(ctx) // []TestTarget

Actions

Endpoints that do more than plain CRUD are exposed as named methods, for example:

err := client.ValidateSite(ctx, &vectorsurv.SiteInput{...})       // validate without saving
err = client.LinkArthropodPoolToCollection(ctx, 11, 22)           // link pool 11 to collection 22
pos, err := client.ArthropodPoolIsPositive(ctx, 11)               // positive pool check
result, err := client.CreateResistanceCalculation(ctx, &vectorsurv.CreateResistanceCalculationInput{Tests: []int{1,2}})
num, err := client.GetNextServiceVisitNumber(ctx, &vectorsurv.GetNextServiceVisitNumberInput{...})
ver, err := client.GetVersion(ctx)                                 // API version

Action methods return the API's response when one is declared, otherwise just error.

Pointers

Fields that are optional or server-managed are pointers (*int, *float64, *bool) so a nil pointer means "absent" and you can distinguish a zero from a missing value. Text fields are plain strings.

CLI

A CLI in cmd/vectorsurv exercises every library function. Build or run it with the Go toolchain from the module root:

go run ./cmd/vectorsurv <command>

Authentication uses the same VECTORSURV_USERNAME / VECTORSURV_PASSWORD environment variables as the library.

List commands

Every resource and reference lookup has a flat list command named after the pluralized record type. Output is JSON.

go run ./cmd/vectorsurv sites
go run ./cmd/vectorsurv collections
go run ./cmd/vectorsurv agencies
go run ./cmd/vectorsurv applications
go run ./cmd/vectorsurv lures
go run ./cmd/vectorsurv testtargets

Group commands (CRUD)

Each resource that supports it has a group command (named after the singular record type) with get, create, update, and delete subcommands. get and delete take the record's ID (plus parent keys for nested resources); create and update read a JSON body from stdin.

go run ./cmd/vectorsurv site get 12345
go run ./cmd/vectorsurv site delete 12345

# create/update read JSON from stdin:
echo '{"name":"Downtown","code":"DTN"}' | go run ./cmd/vectorsurv site create
echo '{"name":"Downtown","code":"DTN","comments":"relocated"}' | go run ./cmd/vectorsurv site update 12345

# nested resources take the parent key first:
go run ./cmd/vectorsurv abundance get 12345 7

Action commands

Action endpoints are exposed as flat commands (camelCased method names). Int and string path parameters are positional; when the action takes a body it is read from stdin as JSON.

go run ./cmd/vectorsurv getversion
go run ./cmd/vectorsurv validatesite
go run ./cmd/vectorsurv linkarthropodpooltocollection 11 22
go run ./cmd/vectorsurv getpopulationclassificationpoint "38.544907, -121.740517"
go run ./cmd/vectorsurv getnextservicevisitnumber   # body from stdin

Flags

• -v, --verbose — enable debug (request) logging.
• -h, --help — command help (also on subcommands).

Set INSECURE_HTTPS to any non-empty value to skip TLS certificate verification (useful when debugging through a proxy such as mitmproxy).

Regenerating the client

The generated files carry a "DO NOT EDIT" header. To regenerate them after the VectorSurv API changes:

# update gen/swagger.json from https://api.vectorsurv.org/swagger.json
curl -s https://api.vectorsurv.org/swagger.json -o gen/swagger.json
go run ./gen
gofmt -w ./*.go ./cmd/vectorsurv/*.go

The generator reads the curated resource/lookup/action tables in gen/tables.go; add or adjust entries there if an endpoint should be modeled differently, then re-run go run ./gen.

License

See LICENSE.