Overview

This package contains 2 high level elements of note.

• openapi.yaml - This is the OpenAPI specification file generated by the generator package in this repository. From this specification, clients and servers can be generated for the Nomad HTTP API. This file is generated and should never be edited by hand.
• This directory contains hand-written go code and associated tests that provide a higher level of abstraction over the generated client. For example, the jobs.go file contains methods that expose all the jobs related endpoints, and jobs_tests.go contains code showing how a calling client might consume those methods. The api.go file contains framework level code related to creating a client instance, generating contexts for query and write operations, as well as helper methods for applying query and write options to requests.

Note: This package is experimental and is likely to change. There is no guarantee of backward compatability, at this time. Method names, signatures, and type names may change as we iterate.

Quick start

Import this package to your project.

go get https://github.com/hashicorp/nomad-openapi

Add an import for the package to your code.

import (
	"github.com/hashicorp/nomad-openapi/v1"
)

Create a client instance.

client, err := NewClient()

All operations are modeled as either queries or writes. Queries require QueryOpts and writes require WriteOpts.

var queryOpts = &QueryOpts{}

queryOpts := queryOpts().
    WithRegion("global")
    WithNamespace("default").
    WithAllowStale(true).
    WithWaitIndex(1000).
    WithWaitTime(100000 * time.Millisecond) // WaitTime is expected to always be defined in milliseconds
    // See QueryOpts struct for all possible QueryOpts.

These options can then be converted to a context, and passed to each API endpoint as the first argument.

result, meta, err := client.Jobs().GetJobs(queryOpts.Ctx())
if err != nil {
	// do error handling
}

• Most endpoint functions returns a result, a meta struct, and an error
• All endpoint functions return an error
• If the error is not nil, both result and meta should be nil and no further evaluation is necessary
• The result will usually be a model from the generated client package, but may also be a golang primitive type like string or int
• The meta struct contains metadata about the state of the server at the time of the response as callers may wish to track things like the last index at the time of the operation
• See the QueryMeta and WriteMeta structs for a full explanation of the metadata returned for query and write operations respectively

Goals

This package has several goals which are listed below.

• Create an opinionated, consistent API DX across all endpoints of the Nomad HTTP API
• Provide a high-level abstraction over the generated client
• Provide an example of how to consume a generated OpenAPI client
• Experiment with context as a first-class citizen of the Nomad API
• Experiment with API versioning and uplift mechanisms
• Experiment with a unified OpenAPI/AsyncAPI client