voki

README

vlbeaudoin/voki

Strongly-typed JSON HTTP API request-response framework for go using only the standard library

Features

• JSON HTTP API caller (*voki.Voki).Call with support for bearer tokens in header;

• JSON HTTP API response unmarshaller (*voki.Voki).Unmarshal which does JSON decoding on top of Call;

• Dedicated JSON API response types with voki.Responder;

• Dedicated JSON API request types linked to a response type with voki.Requester[R voki.Responder];

• Reusable and embeddable structs for a basic response type with voki.Response;

Breaking changes in v2.x.x

For more details, see the pull-request for version-2

Packages request and response moved to base voki package

From this change on, all types, methods and functions declared are accessible in the voki.* package.

This was the main reason for moving to version 2 with breaking changes, is that now the interfaces are more ingrained in the voki name. Also, this prevents the silly overlap of request and response concepts in http with voki's concept of processed Request and Response types.

It seems clearer to me that a voki.Request is not necessarily equivalent to a http.Request, which was a point of confusion in the module.

Interface voki.Complete renamed to voki.Completer

More uniform with usual naming scheme of single-method interfaces.

Resources

• Issues: https://codeberg.org/vlbeaudoin/voki/issues

• Repository: https://codeberg.org/vlbeaudoin/voki

• Go module documentation: https://pkg.go.dev/codeberg.org/vlbeaudoin/voki

Attributions

The voki logo was made using caro-asercion/rotary-phone which is licensed under CC BY 3.0.

The voki Codeberg badge was made using GetItOnCodeberg

Documentation

Overview

Package voki provides a strongly-typed JSON HTTP API request-response framework

It is lightweight and built directly on top of the Go standard library

Index

• type Completer
• type Requester
• type Responder
• type Response
  • func (r Response) Respond() Responder
• type ResponseWithError
• type Voki
  • func New(client *http.Client, host, key string, port int, protocol string) *Voki
  • func (v *Voki) Call(method, route string, requestBody io.Reader, useKey bool) (*http.Response, error)
  • func (v *Voki) CloseIdleConnections()
  • func (v *Voki) Complete() bool
  • func (v *Voki) Unmarshal(method, route string, requestBody io.Reader, useKey bool, destination any) error
  • func (v *Voki) UnmarshalIfComplete(method, route string, requestBody io.Reader, useKey bool, destination any) error

Types

type Completer

type Completer interface {
	Complete() bool
}

Completer is a single-method interface to allow structs to declare themselves as `Complete` by returning an boolean.

It is used by `Voki.UnmarshalIfComplete` by checking some or all of their fields and returning `True` if they consider themselves ready to be sent to an API server, or `False` if not.

type Requester

type Requester[R Responder] interface {
	Completer

	// Request should only run if Complete() is true
	Request(*Voki) (R, error)
}

type Responder

type Responder interface {
	Respond() Responder
}

Responder is used to define objects that can be unmarshalled into by (*voki.Voki).CallResponder.

type Response

type Response struct {
	StatusCode int
	Message    string
}

Response declares fields used by most of my API servers.

They will probably not apply to your environment, if so declare structs that implement the Responder interface, so that you can use them with (*voki.Voki).CallResponder.

Example:

// Instantiate a new *http.Client
client := http.DefaultClient
defer client.CloseIdleConnections()

// Instantiate a new *voki.Voki.
v := voki.New(client, ...) // Replace ... with your API server details

// MyResponse must match some or all of the fields returned by the API
// endpoint
type MyResponse struct {
  response.Response
  Data struct {
      MyString string
  }
}

var myResponse MyResponse

// Replace "/v1/myresource" by the API endpoint you are trying to reach
// relative to the connection informations defined in voki.New(...).
//
// Note that in this case, calling v.CallResponder and v.Unmarshal
// accomplishes the same goal, but only because MyResponse implements
// response.Responder.
if err := v.CallResponder(http.MethodGet, "/v1/myresource", nil, false, &myResponse); err != nil {
  log.Fatal(err)
}

fmt.Println(myResponse.StatusCode) // Output: 200

func (Response) Respond

func (r Response) Respond() Responder

Respond implements Responder interface for Response

type ResponseWithError

type ResponseWithError struct {
	Response
	Error string
}

type Voki

type Voki struct {
	Client   *http.Client
	Host     string
	Key      string
	Port     int
	Protocol string
}

Voki is the base of the project, and contains a reuseable *http.Client for API requests, along with the connection information for the API server to be queried.

It also implements methods to make calls against that API server with (*Voki).Call, as well as unmarshalling the result into a struct with (*Voki).Unmarshal.

It is recommended to use New() to instanciate a pointer to a new Voki client.

func New

func New(client *http.Client, host, key string, port int, protocol string) *Voki

func (*Voki) Call

func (v *Voki) Call(method, route string, requestBody io.Reader, useKey bool) (*http.Response, error)

(*Voki).Call returns a *http.Response and optionally an error, after requesting an API resource.

This is used by (*Voki).Unmarshal to make the actual request, and that method should generally be used over (*Voki).Call.

However, should you need access to the underlying *http.Response, you may use this method yourself instead.

func (*Voki) CloseIdleConnections

func (v *Voki) CloseIdleConnections()

CloseIdleConnections calls the eponymous method on (*Voki).Client

func (*Voki) Complete

func (v *Voki) Complete() bool

Complete checks if the different fields of a `Voki` instance are ready for http requests

func (*Voki) Unmarshal

func (v *Voki) Unmarshal(method, route string, requestBody io.Reader, useKey bool, destination any) error

Unmarshal makes a (*Voki).Call() returning only an error. The Call data is put into the `destination` parameter.

Example:

// Instantiate a new *http.Client
client := http.DefaultClient
defer client.CloseIdleConnections()

// Instantiate a new *voki.Voki.
v := voki.New(client, ...) // Replace ... with your API server details

// MyStruct must match some or all of the fields returned by the API
// endpoint
type MyStruct struct {
    MyInt    int
    MyString string
}

var destinationStruct MyStruct

// Replace "/v1/myresource" by the API endpoint you are trying to reach
// relative to the connection informations defined in voki.New(...)
if err := v.Unmarshal(http.MethodGet, "/v1/myresource", nil, false, &destinationStruct); err != nil {
  log.Fatal(err)
}

fmt.Println(MyStruct) // Output: <content of destinationStruct>

func (*Voki) UnmarshalIfComplete

func (v *Voki) UnmarshalIfComplete(method, route string, requestBody io.Reader, useKey bool, destination any) error