voki

README

vlbeaudoin/voki

Strongly-typed JSON HTTP API request-response framework for go

Packages

Package codeberg.org/vlbeaudoin/voki is a JSON API caller and response unmarshaller

Package codeberg.org/vlbeaudoin/voki/response allows declaring explicit JSON API response types

Package codeberg.org/vlbeaudoin/voki/request allows declaring explicit JSON API request types

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

Logo attributions

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

Documentation

Overview

Package voki provides a JSON API client with reuseable logic to make requests against a JSON API server.

Index

• type Complete
• 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) CallResponder(method, route string, requestBody io.Reader, useKey bool, ...) 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 Complete

type Complete interface {
	Complete() bool
}

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

func (v *Voki) CallResponder(method, route string, requestBody io.Reader, useKey bool, responder response.Responder) error

Deprecated: Please switch to (*Voki).Unmarshal. This method will be removed in a future version.

Makes Voki.Call() returning only an error. The Call data is put into the responder parameter's reference

Example:

// Replace ... in parentheses by your environment's values
v := voki.New(...)

type MyResponse struct {
  responses.Response
  Data struct {
      MyString string
  }
}

var myResponse MyResponse

// Replace "/v1/myresource" by the API endpoint you are trying to reach
if err := v.CallResponder(http.MethodGet, "/v1/myresource", nil, false, &myResponse); err != nil {
  log.Fatal(err)
}

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

func (*Voki) CloseIdleConnections

func (v *Voki) CloseIdleConnections()

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

func (*Voki) Complete

func (v *Voki) Complete() bool

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