rip

README

go-rip

Small library for making json rest calls. go-rip provides fluent chainable api that makes doing rest calls reslly simple.

name

Why the name? Well rest in peace fits quite good as rest api client.

Install

You can install this library simply by typing:

go get github.com/phonkee/go-rip

Examples:

Let's see this library in action. First let's create a client that we will use in all examples

client := rip.New("http://127.0.0.1/api/v1")

Client has even more methods to add:

• Headers - add default headers for all method calls
• AppendSlash - add trailing slash if not presented
• Base - set base url
• Client - set custom http.Client instead of default ones
• Data - add data to be sent as body, data can be:
  • string - is converted to []byte
  • byte[] - sent as is
  • other - will be json Marshalled to []byte
• Path - add path prefix
• QueryValues - add query values (query parameters)
• UserAgent - set custom user agent instead of default one

Now let's make a http GET request.

type Product struct {}

product = Product{}
status := 0
if err := client.Get("product", 1).Do(context.Background(), &product).Status(&status).Error(); err != nil {
    panic("oops")
}

This makes a http GET call to "http://127.0.0.1/api/v1/product/1/" and unmarshals result to product variable. We are also handling errors and filling status variable with http status code in the same line. Isn't that nice?

You can see that go-rip uses golangs context for http requests and must be passed as first argument to Do method.

Let's make a POST request with some data.

product = Product{}
result = map[string]interface{}
if err := client.Post("product", 1).Data(product).Do(context.Background(), &result).Error(); err != nil {
    panic(err)
}

We just made http POST request to "http://127.0.0.1/api/v1/product/1/" and we sent body of the request json marshalled product. Ain't that really nice?

author

Peter Vrba phonkee@phonkee.eu

Documentation

Overview

go-rip is simple rest json api client. It has fluent chainable api, so you can do request along with unmarshalling and error checking on single line.

First we prepare client that we will use in later examples:

client := rip.New("http://localhost/api/v1").Header("Token", "Token").AppendSlash(true)

Now we can have a look at some examples of rest json api calls

type Product struct {}
product := Product{}

status := 0

if err := client.Get("product", 1).Do(context.Background(), &product).Status(&status); err != nil {
	panic(err)
}

In this example we did following:

• make GET http request to http://localhost/api/v1/product/1/
• we have unmarshalled json response to `product` variable
• we have set http status code into `status` variable
• we have checked for error

This is awesome!

Majority of methods return Client so you can chain your calls. Structures are immutable, so chaining creates new struct. Do method returns response, which provides also useful methods.

Let's do POST http call

if err := client.Post("product").Data(product).Do(context.Background()).Status(&status).Error(); err != nil {
	panic(err)
}

Index

• Constants
• type Client
  • func New(baseUrl ...string) (result Client)
• type Response

Constants

const (
	DefaultUserAgent = "rip-1.0"
)

Types

type Client

type Client interface {

	// AppendSlash adds slashes on the end when not presented
	AppendSlash(bool) Client

	// Base sets base url, all rest endpoints are added to this url.
	Base(string) Client

	// BeforeSend you can change request
	BeforeSend(func(r *http.Request)) Client

	// Client override default http client.
	Client(func() *http.Client) Client

	// Data sets data to be marshalled to json
	Data(interface{}) Client

	// FromResponse constructs Response from *http.Response
	FromResponse(hr *http.Response) Response

	// Do performs request and returns Response
	Do(ctx context.Context, target ...interface{}) Response

	// Header sets header for request
	Header(key, value string) Client

	// Method sets http method
	Method(method string, parts ...interface{}) Client

	// Path sets path
	Path(parts ...interface{}) Client

	// QueryValues
	QueryValues(values url.Values) Client

	// Request returns prepared request
	Request() *http.Request

	// URL returns actual rest endpoint url
	URL() *url.URL

	// UserAgent overrides default user agent
	UserAgent(agent string) Client

	// Delete HTTP method
	Delete(parts ...interface{}) Client

	// Get HTTP method
	Get(parts ...interface{}) Client

	// Head HTTP method
	Head(parts ...interface{}) Client

	// Options HTTP method
	Options(parts ...interface{}) Client

	// Patch HTTP method
	Patch(parts ...interface{}) Client

	// Put HTTP method
	Put(parts ...interface{}) Client

	// Post HTTP method
	Post(parts ...interface{}) Client
}

Client main object in go-rip. most of methods are chainable, so it provides nice fluent api. When Do method is called, Response is returned. This Response is wrapper around http.Response with useful methods.

func New

func New(baseUrl ...string) (result Client)

New returns new client You can provide baseUrl or you can call Base method

New("http://localhost")

is equal to

New().Base("http://localhost")

type Response

type Response interface {

	// Body returns response body, if there was an error blank []byte will be returned
	Body() []byte

	// RawBody returns raw body response
	Raw(*[]byte) Response

	// Client returns original client who made the request. This is useful in retry scenarios.
	Client() Client

	// Do calls Do method on client.
	Do(ctx context.Context, target ...interface{}) Response

	// Error returns error if occurred
	Error() error

	// Header returns http header
	Header() http.Header

	// Status fills status into given pointer
	Status(*int) Response

	// Unmarshal unmarshals json response into target
	Unmarshal(target interface{}) Response
}

Response is rest response representation. It wraps http.Response, and has body already read.