rest

README

Quickly and easily access any RESTful or RESTful-like API.

If you are looking for the SendGrid API client library, please see this repo.

Announcements

All updates to this library is documented in our CHANGELOG.

Table of Contents

• Installation
• Quick Start
• Usage
• Roadmap
• How to Contribute
• About
• License

Installation

Prerequisites

• Go version 1.6.X, 1.7.X, 1.8.X, 1.9.X or 1.10.X

Install Package

go get github.com/sendgrid/rest

Setup Environment Variables

Initial Setup

cp .env_sample .env

Environment Variable

Update the development environment with your SENDGRID_API_KEY, for example:

echo "export SENDGRID_API_KEY='YOUR_API_KEY'" > sendgrid.env
echo "sendgrid.env" >> .gitignore
source ./sendgrid.env

Quick Start

GET /your/api/{param}/call

package main

import "github.com/sendgrid/rest"
import "fmt"

func main() {
	const host = "https://api.example.com"
	param := "myparam"
	endpoint := "/your/api/" + param + "/call"
	baseURL := host + endpoint
	method := rest.Get
	request := rest.Request{
		Method:  method,
		BaseURL: baseURL,
	}
	response, err := rest.Send(request)
	if err != nil {
		fmt.Println(err)
	} else {
		fmt.Println(response.StatusCode)
		fmt.Println(response.Body)
		fmt.Println(response.Headers)
	}
}

POST /your/api/{param}/call with headers, query parameters and a request body.

package main

import "github.com/sendgrid/rest"
import "fmt"

func main() {
	const host = "https://api.example.com"
	param := "myparam"
	endpoint := "/your/api/" + param + "/call"
	baseURL := host + endpoint
	Headers := make(map[string]string)
	key := os.Getenv("API_KEY")
	Headers["Authorization"] = "Bearer " + key
	Headers["X-Test"] = "Test"
	var Body = []byte(`{"some": 0, "awesome": 1, "data": 3}`)
	queryParams := make(map[string]string)
	queryParams["hello"] = "0"
	queryParams["world"] = "1"
	method := rest.Post
	request = rest.Request{
		Method:      method,
		BaseURL:     baseURL,
		Headers:     Headers,
		QueryParams: queryParams,
		Body:        Body,
	}
	response, err := rest.Send(request)
	if err != nil {
		fmt.Println(err)
	} else {
		fmt.Println(response.StatusCode)
		fmt.Println(response.Body)
		fmt.Println(response.Headers)
	}
}

Usage

• Usage Examples

Roadmap

If you are interested in the future direction of this project, please take a look at our milestones. We would love to hear your feedback.

How to Contribute

We encourage contribution to our projects, please see our CONTRIBUTING guide for details.

Quick links:

• Feature Request
• Bug Reports
• Sign the CLA to Create a Pull Request
• Improvements to the Codebase

About

rest is guided and supported by the SendGrid Developer Experience Team.

rest is maintained and funded by SendGrid, Inc. The names and logos for rest are trademarks of SendGrid, Inc.

License

The MIT License (MIT)

Documentation

Overview

Package rest allows for quick and easy access any REST or REST-like API.

Index

• Variables
• func AddQueryParameters(baseURL string, queryParams map[string]string) string
• func BuildRequestObject(request Request) (*http.Request, error)
• func MakeRequest(req *http.Request) (*http.Response, error)
• type Client
  • func (c *Client) API(request Request) (*Response, error)
  • func (c *Client) MakeRequest(req *http.Request) (*http.Response, error)
  • func (c *Client) Send(request Request) (*Response, error)
• type Method
• type Request
• type Response
  • func API(request Request) (*Response, error)
  • func BuildResponse(res *http.Response) (*Response, error)
  • func Send(request Request) (*Response, error)
• type RestError
  • func (e *RestError) Error() string

Variables

var DefaultClient = &Client{HTTPClient: http.DefaultClient}

DefaultClient is used if no custom HTTP client is defined

Functions

func AddQueryParameters

func AddQueryParameters(baseURL string, queryParams map[string]string) string

AddQueryParameters adds query parameters to the URL.

func BuildRequestObject

func BuildRequestObject(request Request) (*http.Request, error)

BuildRequestObject creates the HTTP request object.

func MakeRequest

func MakeRequest(req *http.Request) (*http.Response, error)

MakeRequest makes the API call.

Types

type Client

type Client struct {
	HTTPClient *http.Client
}

Client allows modification of client headers, redirect policy and other settings See https://golang.org/pkg/net/http

func (*Client) API

func (c *Client) API(request Request) (*Response, error)

API supports old implementation (deprecated)

func (*Client) MakeRequest

func (c *Client) MakeRequest(req *http.Request) (*http.Response, error)

MakeRequest makes the API call.

func (*Client) Send

func (c *Client) Send(request Request) (*Response, error)

Send will build your request, make the request, and build your response.

type Method

type Method string

Method contains the supported HTTP verbs.

const (
	Get    Method = "GET"
	Post   Method = "POST"
	Put    Method = "PUT"
	Patch  Method = "PATCH"
	Delete Method = "DELETE"
)

Supported HTTP verbs.

type Request

type Request struct {
	Method      Method
	BaseURL     string // e.g. https://api.sendgrid.com
	Headers     map[string]string
	QueryParams map[string]string
	Body        []byte
}

Request holds the request to an API Call.

type Response

type Response struct {
	StatusCode int                 // e.g. 200
	Body       string              // e.g. {"result: success"}
	Headers    map[string][]string // e.g. map[X-Ratelimit-Limit:[600]]
}

Response holds the response from an API call.

func API

func API(request Request) (*Response, error)

API supports old implementation (deprecated)

func BuildResponse

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

BuildResponse builds the response struct.

func Send

func Send(request Request) (*Response, error)

Send uses the DefaultClient to send your request

type RestError

type RestError struct {
	Response *Response
}

RestError is a struct for an error handling.

func (*RestError) Error

func (e *RestError) Error() string

Error is the implementation of the error interface.