restclient

README

REST Client

This package provides a set of services and mocks for working with and testing REST services. An interface is provided to abstract the type of data you work with, and a concrete JSON-data implementation is provided.

HTTPClientInterface

HTTPClientInterface provides an interface to the Go HTTP client. This allows your services to mock HTTP interactions for unit testing.

type HTTPClientInterface interface {
	Do(req *http.Request) (*http.Response, error)
}

As you can see this interface matches the Go http.Client struct, allowing you to use it to fulfill services that depend on the HTTPClientInterface.

JSONClient

JSONClient is used to communicate with REST APIs that deal with JSON inputs and outputs. This service implements the RESTClient interface.

httpClient := &http.Client{} // Here you could use MockHTTPClient for unit tests
client := restclient.NewJSONClient("http://localhost:8080", httpClient)

If you want your requests to include an authorization header that would look like this.

httpClient := &http.Client{} // Here you could use MockHTTPClient for unit tests
client := restclient.NewJSONClient("http://localhost:8080", httpClient).WithAuthorization("Bearer " + token)

DELETE

DELETE performs an HTTP DELETE operation. You provide a path, which should exclude the TLD, as this is defined in BaseURL.

If some type of error occurs when creating the request, executing the request, or unmarshalling the response, err will be populated. The http.Response is returned so callers can inspect the status.

successResponse := SuccessStruct{}
errorResponse := ErrorStruct{}

response, err := client.DELETE("/thing", &successResponse, &errorResponse)

if err != nil {
	// Handle the error here
}

if response.Status > 299 {
	// Uh oh, non-success response. errorResponse contains whatever
	// JSON came back
}

// successResponse contains whatever JSON came back from success

GET

GET performs an HTTP GET operation. You provide a path, which should exclude the TLD, as this is defined in BaseURL.

If some type of error occurs when creating the request, executing the request, or unmarshalling the response, err will be populated. The http.Response is returned so callers can inspect the status.

successResponse := SuccessStruct{}
errorResponse := ErrorStruct{}

response, err := client.GET("/thing", &successResponse, &errorResponse)

if err != nil {
	// Handle the error here
}

if response.Status > 299 {
	// Uh oh, non-success response. errorResponse contains whatever
	// JSON came back
}

// successResponse contains whatever JSON came back from success

POST

POST performs an HTTP POST operation. You provide a path, which should exclude the TLD, as this is defined in BaseURL. The body of the post is an interface, allowing you to pass whatever you wish, and it will be serialized to JSON.

If some type of error occurs when creating the request, executing the request, or unmarshalling the response, err will be populated. The http.Response is returned so callers can inspect the status.

successResponse := SuccessStruct{}
errorResponse := ErrorStruct{}

body := SomeStruct{
	SomeKey1: "somevalue1",
	SomeKey2: 2,
}

response, err := client.POST("/thing", body, &successResponse, &errorResponse)

if err != nil {
	// Handle the error here
}

if response.Status > 299 {
	// Uh oh, non-success response. errorResponse contains whatever
	// JSON came back
}

// successResponse contains whatever JSON came back from success

PUT

PUT performs an HTTP PUT operation. You provide a path, which should exclude the TLD, as this is defined in BaseURL. The body of the put is an interface, allowing you to pass whatever you wish, and it will be serialized to JSON.

If some type of error occurs when creating the request, executing the request, or unmarshalling the response, err will be populated. The http.Response is returned so callers can inspect the status.

successResponse := SuccessStruct{}
errorResponse := ErrorStruct{}

body := SomeStruct{
	SomeKey1: "somevalue1",
	SomeKey2: 2,
}

response, err := client.PUT("/thing", body, &successResponse, &errorResponse)

if err != nil {
	// Handle the error here
}

if response.Status > 299 {
	// Uh oh, non-success response. errorResponse contains whatever
	// JSON came back
}

// successResponse contains whatever JSON came back from success

WithAuthorization

WithAuthorization returns a copy of this JSONClient with the Authorization header set. Subsequent HTTP requests will send Authorization: <auth>, with auth being whatever you set in the string argument.

httpClient := &http.Client{} // Here you could use MockHTTPClient for unit tests
client := restclient.NewJSONClient("http://localhost:8080", httpClient).WithAuthorization("Bearer " + token)

Documentation

Index

• type HTTPClient
  • func (h *HTTPClient) Do(req *http.Request) (*http.Response, error)
  • func (h *HTTPClient) SetTransport(transport *http.Transport)
• type HTTPClientInterface
• type JSONClient
  • func NewJSONClient(baseURL string, httpClient HTTPClientInterface) JSONClient
  • func (c JSONClient) DELETE(path string, successReceiver, errorReceiver interface{}) (*http.Response, error)
  • func (c JSONClient) GET(path string, successReceiver, errorReceiver interface{}) (*http.Response, error)
  • func (c JSONClient) POST(path string, body, successReceiver, errorReceiver interface{}) (*http.Response, error)
  • func (c JSONClient) PUT(path string, body, successReceiver, errorReceiver interface{}) (*http.Response, error)
  • func (c JSONClient) WithAuthorization(auth string) RESTClient
• type MockHTTPClient
  • func (m *MockHTTPClient) Do(req *http.Request) (*http.Response, error)
  • func (m *MockHTTPClient) SetTransport(transport *http.Transport)
• type MockRESTClient
  • func (m MockRESTClient) DELETE(path string, successReceiver, errorReceiver interface{}) (bool, error)
  • func (m MockRESTClient) GET(path string, successReceiver, errorReceiver interface{}) (bool, error)
  • func (m MockRESTClient) POST(path string, body, successReceiver, errorReceiver interface{}) (bool, error)
  • func (m MockRESTClient) PUT(path string, body, successReceiver, errorReceiver interface{}) (bool, error)
  • func (m MockRESTClient) WithAuthorization(auth string) RESTClient
• type RESTClient

Types

type HTTPClient

type HTTPClient struct {
	*http.Client
}

HTTPClient implements methods as a wrapper over the Go HttpClient

func (*HTTPClient) Do

func (h *HTTPClient) Do(req *http.Request) (*http.Response, error)

Do executes this HTTP request

func (*HTTPClient) SetTransport

func (h *HTTPClient) SetTransport(transport *http.Transport)

SetTransport sets the transport information for this HTTP client

type HTTPClientInterface

type HTTPClientInterface interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPClientInterface is an interface over the Go HttpClient

type JSONClient

type JSONClient struct {
	BaseURL    string
	HTTPClient HTTPClientInterface
	// contains filtered or unexported fields
}

JSONClient provides a set of methods for working with RESTful endpoints that accept and return JSON data

func NewJSONClient

func NewJSONClient(baseURL string, httpClient HTTPClientInterface) JSONClient

NewJSONClient creates a new JSON-based REST client

func (JSONClient) DELETE

func (c JSONClient) DELETE(path string, successReceiver, errorReceiver interface{}) (*http.Response, error)

DELETE performs an HTTP DELETE operation. You provide a path, which should exclude the TLD, as this is defined in BaseURL. If your request requires authorization call WithAuthorization first, then DELETE.

If some type of error occurs when creating the request, executing the request, or unmarshalling the response, err will be populated. The http.Response is returned so callers can inspect the status.

func (JSONClient) GET

func (c JSONClient) GET(path string, successReceiver, errorReceiver interface{}) (*http.Response, error)

GET performs an HTTP GET operation. You provide a path, which should exclude the the TLD, as this is defined in BaseURL. If your request requires authorization call WithAuthorization first, then GET.

If some type of error occurs when creating the request, executing the request, or unmarshalling the response, err will be populated. The http.Response is returned so callers can inspect the status.

func (JSONClient) POST

func (c JSONClient) POST(path string, body, successReceiver, errorReceiver interface{}) (*http.Response, error)

POST performs an HTTP POST operation. You provide a path, which should exclude the the TLD, as this is defined in BaseURL. If your request requires authorization call WithAuthorization first, then POST.

If some type of error occurs when creating the request, executing the request, or unmarshalling the response, err will be populated. The http.Response is returned so callers can inspect the status.

func (JSONClient) PUT

func (c JSONClient) PUT(path string, body, successReceiver, errorReceiver interface{}) (*http.Response, error)

PUT performs an HTTP PUT operation. You provide a path, which should exclude the the TLD, as this is defined in BaseURL. If your request requires authorization call WithAuthorization first, then PUT.

If some type of error occurs when creating the request, executing the request, or unmarshalling the response, err will be populated. The http.Response is returned so callers can inspect the status.

func (JSONClient) WithAuthorization

func (c JSONClient) WithAuthorization(auth string) RESTClient

WithAuthorization returns an instance of RESTClient with an authorization header set

type MockHTTPClient

type MockHTTPClient struct {
	DoFunc           func(req *http.Request) (*http.Response, error)
	SetTransportFunc func(transport *http.Transport)
}

MockHTTPClient is a mock HTTP client

func (*MockHTTPClient) Do

func (m *MockHTTPClient) Do(req *http.Request) (*http.Response, error)

Do mocks the HTTP Do method

func (*MockHTTPClient) SetTransport

func (m *MockHTTPClient) SetTransport(transport *http.Transport)

SetTransport mocks the SetTransport method

type MockRESTClient

type MockRESTClient struct {
	DELETEFunc            func(path string, successReceiver, errorReceiver interface{}) (bool, error)
	GETFunc               func(path string, successReceiver, errorReceiver interface{}) (bool, error)
	POSTFunc              func(path string, body, successReceiver, errorReceiver interface{}) (bool, error)
	PUTFunc               func(path string, body, successReceiver, errorReceiver interface{}) (bool, error)
	WithAuthorizationFunc func(auth string) RESTClient
}

MockRESTClient is a mock for RESTClient

func (MockRESTClient) DELETE

func (m MockRESTClient) DELETE(path string, successReceiver, errorReceiver interface{}) (bool, error)

DELETE is a mock method

func (MockRESTClient) GET

func (m MockRESTClient) GET(path string, successReceiver, errorReceiver interface{}) (bool, error)

GET is a mock method

func (MockRESTClient) POST

func (m MockRESTClient) POST(path string, body, successReceiver, errorReceiver interface{}) (bool, error)

POST is a mock method

func (MockRESTClient) PUT

func (m MockRESTClient) PUT(path string, body, successReceiver, errorReceiver interface{}) (bool, error)

PUT is a mock method

func (MockRESTClient) WithAuthorization

func (m MockRESTClient) WithAuthorization(auth string) RESTClient

WithAuthorization is a mock method

type RESTClient

type RESTClient interface {
	DELETE(path string, successReceiver, errorReceiver interface{}) (*http.Response, error)
	GET(path string, successReceiver, errorReceiver interface{}) (*http.Response, error)
	POST(path string, body, successReceiver, errorReceiver interface{}) (*http.Response, error)
	PUT(path string, body, successReceiver, errorReceiver interface{}) (*http.Response, error)
	WithAuthorization(auth string) RESTClient
}

RESTClient defines an interface for working with RESTful endpoints