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 v3.x.x

For more details see the pull-request for version-3

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 MessageResponse
• type Requester
• type Responder
• type ResponseBadRequest
  • func (r ResponseBadRequest) StatusCode() int
• type ResponseCreated
  • func (r ResponseCreated) StatusCode() int
• type ResponseInternalServerError
  • func (r ResponseInternalServerError) StatusCode() int
• type ResponseNoContent
  • func (r ResponseNoContent) StatusCode() int
• type ResponseNotFound
  • func (r ResponseNotFound) StatusCode() int
• type ResponseOK
  • func (r ResponseOK) StatusCode() int
• type ResponseUnauthorized
  • func (r ResponseUnauthorized) StatusCode() int
• 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) CallAndParse(method, route string, requestBody io.Reader, useKey bool) (statusCode int, body []byte, err 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 MessageResponse

type MessageResponse struct {
	Message string `csv:"message" json:"message" yaml:"message"`
}

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 {
	StatusCode() int
}

type ResponseBadRequest

type ResponseBadRequest struct {
	MessageResponse
}

func (ResponseBadRequest) StatusCode

func (r ResponseBadRequest) StatusCode() int

type ResponseCreated

type ResponseCreated struct {
	MessageResponse
}

func (ResponseCreated) StatusCode

func (r ResponseCreated) StatusCode() int

type ResponseInternalServerError

type ResponseInternalServerError struct {
	MessageResponse
}

func (ResponseInternalServerError) StatusCode

func (r ResponseInternalServerError) StatusCode() int

type ResponseNoContent

type ResponseNoContent struct{}

func (ResponseNoContent) StatusCode

func (r ResponseNoContent) StatusCode() int

type ResponseNotFound

type ResponseNotFound struct {
	MessageResponse
}

func (ResponseNotFound) StatusCode

func (r ResponseNotFound) StatusCode() int

type ResponseOK

type ResponseOK struct {
	MessageResponse
}

func (ResponseOK) StatusCode

func (r ResponseOK) StatusCode() int

type ResponseUnauthorized

type ResponseUnauthorized struct {
	MessageResponse
}

func (ResponseUnauthorized) StatusCode

func (r ResponseUnauthorized) StatusCode() int

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) CallAndParse

func (v *Voki) CallAndParse(method, route string, requestBody io.Reader, useKey bool) (statusCode int, body []byte, err error)

CallAndParse is a wrapper around (*voki).Call that only returns a statusCode and body instead of a *http.Response.

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