jsonhttpc

README

JSON-specialized HTTP client

Package jsonhttpc provides a way to easily send and receive HTTP requests with JSON bodies.

• Request and response is encoded/decoded as JSON automatically.
• Bit handy for repeating requests.
  • specify base URL - WithBaseURL()
  • specify HTTP Client - WithClient()
  • specify HTTP header - WithHeader()
• Tips to customize requests - for Do()
  • ContentType() string on body overrides "Content-Type" header. (default is "application/json")
• Responses are automatically JSON-decoded even in case of errors - Error
  • Most of JSON properties are put into Properties map[string]interface{}
  • Error responses that follow RFC7808 Problem Details for HTTP APIs are a bit easier to handle.

(Japanese)

• リクエストとレスポンスは自動的にJSONエンコード/デコードされます
• リクエストを繰り返し行うのに少し便利です
  • ベースURLを設定できる WithBaseURL()
  • HTTP Clientを設定できる WithClient()
  • ヘッダーを設定できる WithHeader()
• リクエストをカスタマイズするtipsがあります - for Do()
  • body に ContentType() string を実装するとContent-Typeヘッダーを変更 できます (デフォルトは application/json)
• エラーの際もレスポンスは自動的にJSONデコードされます
  • Error.Properties に map[string]interface{} で入ります
  • RFC7808 Problem Details for HTTP APIs は少し楽できます

Install and update

$ go get github.com/koron-go/jsonhttpc@latest

How to use

Documentation

Overview

Package jsonhttpc provides a way to easily send and receive HTTP requests with JSON bodies.

Index

• Variables
• func Do(ctx context.Context, method, pathOrURL string, body, receiver interface{}) error
• func Path(s string, p Params) string
• type Client
  • func New(baseURL *url.URL) *Client
  • func (c *Client) Clone() *Client
  • func (c *Client) Do(ctx context.Context, method, pathOrURL string, body, receiver interface{}) error
  • func (c *Client) WithBaseURL(u *url.URL) *Client
  • func (c *Client) WithClient(hc *http.Client) *Client
  • func (c *Client) WithHeader(h http.Header) *Client
  • func (c *Client) WithRequestLogger(l RequestLogger) *Client
  • func (c *Client) WithRequestResponseLogger(l RequestResponseLogger) *Client
  • func (c *Client) WithResponseLogger(l ResponseLogger) *Client
• type Error
  • func (er *Error) Error() string
• type Params
• type RequestLogger
• type RequestResponseLogger
• type ResponseLogger
• type SystemError
  • func (se *SystemError) Error() string
  • func (se *SystemError) Unwrap() error

Variables

var (
	// ErrEmptyResponse is received empty response unexpectedly.
	// Ex. StatusCode shows success but Content-Length is 0.
	// This is a server side error.
	ErrEmptyResponse = errors.New("unexpected empty response")

	// ErrReceiverAbsence means `receiver` is nil.
	// Server responded with body, but user did't provide any receivers.
	// This is a user side error.
	ErrReceiverAbsence = errors.New("receiver absence")
)

var DefaultClient = &Client{}

DefaultClient is used for `jsonhttpc.Do()` for convenience.

Functions

func Do

func Do(ctx context.Context, method, pathOrURL string, body, receiver interface{}) error

Do makes a HTTP request to the server with JSON body, and parse a JSON in response body using `DefaultClient`.

See `Client.Do()` for details.

func Path

func Path(s string, p Params) string

Path provides path templating.

"{foo}" in `s` are replaced with `fmt.Sprint(p["foo"])`. '\' escapes a rune succeeding.

This returns a string with prefix "jsonhttpc.Parse error: " if detects some errors.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a JSON specialized HTTP client.

func New

func New(baseURL *url.URL) *Client

New creates a new Client with base URL. You can pass nil to baseURL, in which case you should pass a complete URL to the pathOrURL argument of Do() function.

func (*Client) Clone

func (c *Client) Clone() *Client

Clone create a clone of Client.

func (*Client) Do

func (c *Client) Do(ctx context.Context, method, pathOrURL string, body, receiver interface{}) error

Do makes a HTTP request to the server with JSON body, and parse a JSON in response body.

`ctx` can be nil, in that case it use `context.Background()` instead.

This returns an error when `pathOrURL` starts with "jsonhttpc.Parse error: " to treat `Path()`'s failure as error.

func (*Client) WithBaseURL

func (c *Client) WithBaseURL(u *url.URL) *Client

WithBaseURL overrides base URL to use.

func (*Client) WithClient

func (c *Client) WithClient(hc *http.Client) *Client

WithClient overrides *http.Client to use.

func (*Client) WithHeader

func (c *Client) WithHeader(h http.Header) *Client

WithHeader overrides http.Header to use.

func (*Client) WithRequestLogger

func (c *Client) WithRequestLogger(l RequestLogger) *Client

WithRequestLogger overrides RequestLogger of the client.

func (*Client) WithRequestResponseLogger

func (c *Client) WithRequestResponseLogger(l RequestResponseLogger) *Client

WithRequestResponseLogger overrides RequestLogger and ResponseLogger with an object in same time.

func (*Client) WithResponseLogger

func (c *Client) WithResponseLogger(l ResponseLogger) *Client

WithResponseLogger overrides ResponseLogger of the client.

type Error

type Error struct {
	StatusCode  int
	Status      string
	ContentType string

	Type     string
	Title    string
	Detail   string
	Instance string

	Properties map[string]interface{}
}

Error is general structure to store error. This supports https://tools.ietf.org/html/rfc7807, if "status" field has some troubles (not string or differ from `StatusCode`, its raw value is put into `Properties`.

func (*Error) Error

func (er *Error) Error() string

Error returns error message.

type Params

type Params map[string]interface{}

Params is a parameters for path templating.

type RequestLogger

type RequestLogger interface {
	LogRequest(context.Context, *http.Request)
}

RequestLogger is a callback with request before make round trip.

type RequestResponseLogger

type RequestResponseLogger interface {
	RequestLogger
	ResponseLogger
}

RequestResponseLogger provides RequestLogger and Response by one object. It is supposed to use with WithRequestResponseLogger.

type ResponseLogger

type ResponseLogger interface {
	LogResponse(context.Context, *http.Response)
}

ResponseLogger is a callback with response after round trip succeeded.

type SystemError

type SystemError struct {
	StatusCode int
	Status     string
	Err        error
}

SystemError is for problems on jsonhttp.

func (*SystemError) Error

func (se *SystemError) Error() string

func (*SystemError) Unwrap

func (se *SystemError) Unwrap() error

Unwrap obtains the based error.