httpclient

README

httpclient is a simple convenience package for performing http/api requests in Go. It wraps the standard libraries net/http package to avoid the repetitive request->decode->closebody logic you're likely so familiar with. Using the lib is very simple - just as with the net/http package you can define a client of your own or use the default. Below is a very basic example.

Usage

package main

import "s32x.com/httpclient"

func main() {
	s, err := httpclient.GetString("https://api.github.com/users/s32x/repos")
	if err != nil {
		panic(err)
	}
	println(s)
}

The BSD 3-clause License

Copyright (c) 2018, Steven Wolfe. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

• Neither the name of httpclient nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Documentation

Index

• Variables
• func Delete(url string) error
• func GetBytes(url string) ([]byte, error)
• func GetJSON(url string, out interface{}) error
• func GetString(url string) (string, error)
• func Head(url string) error
• type Client
  • func New() *Client
  • func (c *Client) Delete(path string, headers map[string]string) error
  • func (c *Client) Do(req *Request) (*Response, error)
  • func (c *Client) DoWithStatus(req *Request, expectedStatus int) (*Response, error)
  • func (c *Client) GetBytes(path string, headers map[string]string) ([]byte, error)
  • func (c *Client) GetJSON(path string, headers map[string]string, out interface{}) error
  • func (c *Client) GetString(path string, headers map[string]string) (string, error)
  • func (c *Client) Head(path string, headers map[string]string) error
  • func (c *Client) PostBytes(path string, headers map[string]string, in []byte) ([]byte, error)
  • func (c *Client) PostJSON(path string, headers map[string]string, in, out interface{}) error
  • func (c *Client) SetBaseURL(url string) *Client
  • func (c *Client) SetHeaders(headers map[string]string) *Client
  • func (c *Client) SetTimeout(timeout time.Duration) *Client
  • func (c *Client) SetTransport(transport *http.Transport) *Client
• type Request
  • func NewRequest(method, path string, headers map[string]string, body []byte) *Request
• type Response
  • func NewResponse(res *http.Response) (*Response, error)

Variables

var DefaultClient = New()

DefaultClient is a basic Client for use without needing to define a Client

Functions

func Delete

func Delete(url string) error

Delete calls Delete using the DefaultClient

func GetBytes

func GetBytes(url string) ([]byte, error)

GetBytes calls GetBytes using the DefaultClient

func GetJSON

func GetJSON(url string, out interface{}) error

GetJSON calls GetJSON using the DefaultClient

func GetString

func GetString(url string) (string, error)

GetString calls GetString using the DefaultClient

func Head

func Head(url string) error

Head calls Head using the DefaultClient

Types

type Client

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

Client is an http.Client wrapper

func New

func New() *Client

New creates a new Client reference given a client timeout

func (*Client) Delete

func (c *Client) Delete(path string, headers map[string]string) error

Delete performs a DELETE request using the passed path and headers. It expects a 200 code status in the response

func (*Client) Do

func (c *Client) Do(req *Request) (*Response, error)

Do performs the passed request and returns a fully populated response

func (*Client) DoWithStatus

func (c *Client) DoWithStatus(req *Request, expectedStatus int) (*Response, error)

DoWithStatus performs the request and asserts the status code on the response

func (*Client) GetBytes

func (c *Client) GetBytes(path string, headers map[string]string) ([]byte, error)

GetBytes performs a GET request using the passed path and headers. It expects a 200 code status in the response and returns the bytes on the response

func (*Client) GetJSON

func (c *Client) GetJSON(path string, headers map[string]string, out interface{}) error

GetJSON performs a basic http GET request and decodes the JSON response into the out interface

func (*Client) GetString

func (c *Client) GetString(path string, headers map[string]string) (string, error)

GetString performs a GET request and returns the response as a string

func (*Client) Head

func (c *Client) Head(path string, headers map[string]string) error

Head performs a HEAD request using the passed path and headers. It expects a 200 status code in the response

func (*Client) PostBytes

func (c *Client) PostBytes(path string, headers map[string]string, in []byte) ([]byte, error)

PostBytes performs a POST request using the passed path, headers and body. It expects a 200 code status in the response and returns the bytes on the response

func (*Client) PostJSON

func (c *Client) PostJSON(path string, headers map[string]string, in, out interface{}) error

PostJSON performs a basic http POST request and decodes the JSON response into the out interface

func (*Client) SetBaseURL

func (c *Client) SetBaseURL(url string) *Client

SetBaseURL sets the baseURL on the Client which will be used on all subsequent requests

func (*Client) SetHeaders

func (c *Client) SetHeaders(headers map[string]string) *Client

SetHeaders sets the headers on the Client which will be used on all subsequent requests

func (*Client) SetTimeout

func (c *Client) SetTimeout(timeout time.Duration) *Client

SetTimeout sets the timeout on the httpclients client

func (*Client) SetTransport

func (c *Client) SetTransport(transport *http.Transport) *Client

SetTransport sets the Transport on the httpclients client

type Request

type Request struct {
	Method  string
	Path    string
	Headers map[string]string
	Body    []byte
}

Request is a basic HTTP request struct containing just what is needed to perform a standard HTTP request

func NewRequest

func NewRequest(method, path string, headers map[string]string, body []byte) *Request

NewRequest builds a new Request with the passed data

type Response

type Response struct {
	StatusCode int
	Headers    map[string][]string
	Body       []byte
}

Response is a basic HTTP response struct containing just the important data returned from an HTTP request

func NewResponse

func NewResponse(res *http.Response) (*Response, error)

NewResponse creates a more basic HTTP Response from the passed http.Response