rest

package module
Version: v2.6.5+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 22, 2021 License: MIT Imports: 5 Imported by: 130

README

SendGrid Logo

Build Status GoDoc Go Report Card Twitter Follow GitHub contributors MIT licensed

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

The default branch name for this repository has been changed to main as of 07/27/2020.

All updates to this library is documented in our CHANGELOG.

Table of Contents

Installation

Prerequisites

  • Go version 1.14, 1.15 or 1.16

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

With Docker

A Docker image has been created to allow you to get started with rest right away.

docker-compose up -d --build

# Ensure the container is running with 'docker ps'
docker ps
CONTAINER ID        IMAGE               COMMAND               CREATED              STATUS              PORTS               NAMES
40c8d984a620        rest_go             "tail -f /dev/null"   About a minute ago   Up About a minute                       rest_go_1

With the container running, you can execute your local go scripts using the following:

# docker exec <container_name> <go command>
docker exec rest_go_1 go run docker/example.go
200
{
  "args": {},
  "headers": {
    "Accept-Encoding": "gzip",
    "Connection": "close",
    "Host": "httpbin.org",
    "User-Agent": "Go-http-client/1.1"
  },
  "origin": "86.180.177.202",
  "url": "https://httpbin.org/get"
}

map[Access-Control-Allow-Origin:[*] Access-Control-Allow-Credentials:[true] Via:[1.1 vegur] Connection:[keep-alive] Server:[gunicorn/19.9.0] Date:[Tue, 02 Oct 2018 18:20:43 GMT] Content-Type:[application/json] Content-Length:[233]]

# You can install libraries too, using the same command
# NOTE: Any libraries installed will be removed when the container is stopped.
docker exec rest_go_1 go get github.com/uniplaces/carbon

Your go files will be executed relative to the root of this directory. So in the example above, to execute the example.go file within the docker directory, we run docker exec rest_go_1 go run docker/example.go. If this file was in the root of this repository (next to README.exe, rest.go etc.), you would run docker exec rest_go_1 go run my_go_script.go

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

How to Contribute

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

Quick links:

About

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

If you need help installing or using the library, please check the Twilio SendGrid Support Help Center.

If you've instead found a bug in the library or would like new features added, go ahead and open issues or pull requests against this repo!

License

The MIT License (MIT)

Documentation

Overview

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

Index

Constants

View Source
const Version = "2.6.5"

Version represents the current version of the rest library

Variables

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

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 deprecated

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

Deprecated: API supports old implementation

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.

func (*Client) SendWithContext

func (c *Client) SendWithContext(ctx context.Context, request Request) (*Response, error)

SendWithContext will build your request passing in the provided context, make the request, and build your response.

type Method added in v1.0.2

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 deprecated

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

Deprecated: API supports old implementation

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

func SendWithContext

func SendWithContext(ctx context.Context, request Request) (*Response, error)

SendWithContext uses the DefaultClient to send your request with the provided context.

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.

Source Files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL