README.md

api-kit

api-kit turns a declarative description of a REST API into a command-line tool. A YAML definition names the resources of an API, how they relate, and the calls that change them; api-kit supplies the rest: authentication and token caching, fetching with pagination, joins across resources, multi-step calls with templates and conditions, and the commands, flags and shell completion that expose all of it.

api-kit ships no API of its own. A binary embeds its definition and calls cli.Run.

Note

api-kit is under construction. Packages land one by one and their APIs change without notice until the first tagged release.

Installation

go get github.com/mittwald/api-kit

api-kit supports Go 1.27 and newer on Linux, macOS and Windows. It builds on cli-kit and cobra.

Packages

Package	What it does
apikit	JSON values that keep key order and number spelling, and error kinds with the exit codes they map to
expr	The small languages of a definition: templates, paths into values, conditions
definition	Loads a definition, merges the user's overlays into it and reports every mistake with its key
auth	Token sources, stored sessions, validation, renewal and logins, as the definition describes them
engine	Requests with caching and retries, listings with pagination, IDs from aliases and searches
output	Results as tables, JSON, YAML, CSV, JSONPath selections and plain lines
cli	The command tree of a tool, generated from its definition, with shell completion
apitest	A scripted fake API for tests, and the definition of an invented pet shop

Example

A definition names the environments of an API and describes its resources:

environments:
  production:
    apis:
      main: https://api.example.test/v1
resources:
  pets:
    columns: [id, name, species]
    filters: ["species="]

A tool embeds it and hands over to cli.Run:

package main

import (
	"context"
	_ "embed"
	"os"

	"github.com/mittwald/cli-kit/buildinfo"

	"github.com/mittwald/api-kit/cli"
	"github.com/mittwald/api-kit/definition"
)

//go:embed definition.yaml
var api []byte

func main() {
	os.Exit(cli.Run(context.Background(), cli.Options{
		Name:       "example",
		Short:      "Query and change the Example API",
		Build:      buildinfo.Get(),
		Definition: definition.Source{Name: "definition.yaml", Data: api},
	}, os.Args[1:]))
}

$ example get pets --filter species=cat
ID        NAME  SPECIES
0a1b2c3e  Tom   cat
$ example get pets 0a1b2c3e -o json

examples/petstore is a complete tool of this kind, with joins, ID aliases, calls that change data and a test that runs it against a fake API.

Versioning

api-kit follows semantic versioning. While it is v0.x, minor releases may change APIs; such changes are listed first in the release notes.

Contributing

Contributions are welcome. See CONTRIBUTING.md for how to build, test and submit changes, and SECURITY.md for reporting vulnerabilities.

License

Copyright (c) 2026 Mittwald CM Service GmbH & Co. KG and contributors

This project is licensed under the MIT License; see the LICENSE file for details.