1 ![SendGrid Logo](https://uiux.s3.amazonaws.com/2016-logos/email-logo%402x.png)

     2 

     3 [![Build Status](https://travis-ci.org/sendgrid/rest.svg?branch=master)](https://travis-ci.org/sendgrid/rest)

     4 [![GoDoc](https://godoc.org/github.com/sendgrid/rest?status.png)](http://godoc.org/github.com/sendgrid/rest)

     5 [![Go Report Card](https://goreportcard.com/badge/github.com/sendgrid/rest)](https://goreportcard.com/report/github.com/sendgrid/rest)

     6 [![Email Notifications Badge](https://dx.sendgrid.com/badge/go)](https://dx.sendgrid.com/newsletter/go)

     7 [![Twitter Follow](https://img.shields.io/twitter/follow/sendgrid.svg?style=social&label=Follow)](https://twitter.com/sendgrid)

     8 [![GitHub contributors](https://img.shields.io/github/contributors/sendgrid/rest.svg)](https://github.com/sendgrid/rest/graphs/contributors)

     9 [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE.txt)

    10 

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

    12 

    13 If you are looking for the SendGrid API client library, please see [this repo](https://github.com/sendgrid/sendgrid-go).

    14 

    15 # Announcements

    16 

    17 All updates to this library is documented in our [CHANGELOG](https://github.com/sendgrid/rest/blob/master/CHANGELOG.md).

    18 

    19 # Table of Contents

    20 - [Installation](#installation)

    21 - [Quick Start](#quick-start)

    22 - [Usage](#usage)

    23 - [Roadmap](#roadmap)

    24 - [How to Contribute](#contribute)

    25 - [About](#about)

    26 - [License](#license)

    27 

    28 <a name="installation"></a>

    29 # Installation

    30 

    31 ## Prerequisites

    32 

    33 - Go version 1.6.X, 1.7.X, 1.8.X, 1.9.X or 1.10.X

    34 

    35 ## Install Package

    36 

    37 ```bash

    38 go get github.com/sendgrid/rest

    39 ```

    40 

    41 ## Setup Environment Variables

    42 

    43 ### Initial Setup

    44 

    45 ```bash

    46 cp .env_sample .env

    47 ```

    48 

    49 ### Environment Variable

    50 

    51 Update the development environment with your [SENDGRID_API_KEY](https://app.sendgrid.com/settings/api_keys), for example:

    52 

    53 ```bash

    54 echo "export SENDGRID_API_KEY='YOUR_API_KEY'" > sendgrid.env

    55 echo "sendgrid.env" >> .gitignore

    56 source ./sendgrid.env

    57 ```

    58 

    59 <a name="quick-start"></a>

    60 # Quick Start

    61 

    62 `GET /your/api/{param}/call`

    63 

    64 ```go

    65 package main

    66 

    67 import "github.com/sendgrid/rest"

    68 import "fmt"

    69 

    70 func main() {

    71 	const host = "https://api.example.com"

    72 	param := "myparam"

    73 	endpoint := "/your/api/" + param + "/call"

    74 	baseURL := host + endpoint

    75 	method := rest.Get

    76 	request := rest.Request{

    77 		Method:  method,

    78 		BaseURL: baseURL,

    79 	}

    80 	response, err := rest.Send(request)

    81 	if err != nil {

    82 		fmt.Println(err)

    83 	} else {

    84 		fmt.Println(response.StatusCode)

    85 		fmt.Println(response.Body)

    86 		fmt.Println(response.Headers)

    87 	}

    88 }

    89 ```

    90 

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

    92 

    93 ```go

    94 package main

    95 

    96 import "github.com/sendgrid/rest"

    97 import "fmt"

    98 

    99 func main() {

   100 	const host = "https://api.example.com"

   101 	param := "myparam"

   102 	endpoint := "/your/api/" + param + "/call"

   103 	baseURL := host + endpoint

   104 	Headers := make(map[string]string)

   105 	key := os.Getenv("API_KEY")

   106 	Headers["Authorization"] = "Bearer " + key

   107 	Headers["X-Test"] = "Test"

   108 	var Body = []byte(`{"some": 0, "awesome": 1, "data": 3}`)

   109 	queryParams := make(map[string]string)

   110 	queryParams["hello"] = "0"

   111 	queryParams["world"] = "1"

   112 	method := rest.Post

   113 	request = rest.Request{

   114 		Method:      method,

   115 		BaseURL:     baseURL,

   116 		Headers:     Headers,

   117 		QueryParams: queryParams,

   118 		Body:        Body,

   119 	}

   120 	response, err := rest.Send(request)

   121 	if err != nil {

   122 		fmt.Println(err)

   123 	} else {

   124 		fmt.Println(response.StatusCode)

   125 		fmt.Println(response.Body)

   126 		fmt.Println(response.Headers)

   127 	}

   128 }

   129 ```

   130 

   131 <a name="usage"></a>

   132 # Usage

   133 

   134 - [Usage Examples](USAGE.md)

   135 

   136 <a name="roadmap"></a>

   137 # Roadmap

   138 

   139 If you are interested in the future direction of this project, please take a look at our [milestones](https://github.com/sendgrid/rest/milestones). We would love to hear your feedback.

   140 

   141 <a name="contribute"></a>

   142 # How to Contribute

   143 

   144 We encourage contribution to our projects, please see our [CONTRIBUTING](https://github.com/sendgrid/rest/blob/master/CONTRIBUTING.md) guide for details.

   145 

   146 Quick links:

   147 

   148 - [Feature Request](https://github.com/sendgrid/rest/blob/master/CONTRIBUTING.md#feature-request)

   149 - [Bug Reports](https://github.com/sendgrid/rest/blob/master/CONTRIBUTING.md#submit-a-bug-report)

   150 - [Sign the CLA to Create a Pull Request](https://github.com/sendgrid/rest/blob/master/CONTRIBUTING.md#cla)

   151 - [Improvements to the Codebase](https://github.com/sendgrid/rest/blob/master/CONTRIBUTING.md#improvements-to-the-codebase)

   152 

   153 <a name="about"></a>

   154 # About

   155 

   156 rest is guided and supported by the SendGrid [Developer Experience Team](mailto:dx@sendgrid.com).

   157 

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

   159 

   160 <a name="license"></a>

   161 # License

   162 [The MIT License (MIT)](LICENSE.txt)