2020-07-11 13:49:07 -04:00
# go-reddit
2020-04-23 20:10:02 -04:00
2020-08-02 19:04:53 -04:00
[![Actions Status ](https://github.com/vartanbeno/go-reddit/workflows/tests/badge.svg )](https://github.com/vartanbeno/go-reddit/actions)
2020-08-25 19:58:03 -04:00
[![Go Report Card ](https://goreportcard.com/badge/github.com/vartanbeno/go-reddit )](https://goreportcard.com/report/github.com/vartanbeno/go-reddit)
2020-08-02 17:24:28 -04:00
2020-07-11 13:49:07 -04:00
go-reddit is a Go client library for accessing the Reddit API.
2020-04-23 22:57:47 -04:00
2020-08-02 15:59:25 -04:00
You can view Reddit's official API documentation [here ](https://www.reddit.com/dev/api/ ).
2020-04-23 22:57:47 -04:00
## Install
2020-07-11 13:49:07 -04:00
To get a specific version from the list of [versions ](https://github.com/vartanbeno/go-reddit/releases ):
2020-04-23 22:57:47 -04:00
```sh
2020-07-11 13:49:07 -04:00
go get github.com/vartanbeno/go-reddit@vX.Y.Z
2020-04-23 22:57:47 -04:00
```
Or for the latest version:
```sh
2020-07-11 13:49:07 -04:00
go get github.com/vartanbeno/go-reddit
2020-04-23 22:57:47 -04:00
```
2020-08-02 15:59:25 -04:00
## Usage
Make sure to have a Reddit app with a valid client id and secret. [Here ](https://github.com/reddit-archive/reddit/wiki/OAuth2-Quick-Start-Example#first-steps ) is a quick guide on how to create an app and get credentials.
```go
package main
2020-08-20 14:37:59 -04:00
import "github.com/vartanbeno/go-reddit/reddit"
2020-08-02 15:59:25 -04:00
func main() {
2020-08-25 20:55:32 -04:00
credentials := & reddit.Credentials{
ID: "id",
Secret: "secret",
Username: "username",
Password: "password",
}
2020-08-26 23:13:34 -04:00
client, _ := reddit.NewClient(credentials)
2020-08-02 15:59:25 -04:00
}
```
2020-08-26 23:13:34 -04:00
You can pass in a number of options to `NewClient` that further configure the client. For example, to use a custom HTTP client:
```go
httpClient := & http.Client{Timeout: time.Second * 30}
client, _ := reddit.NewClient(credentials, reddit.WithHTTPClient(httpClient))
```
If this option is not used, it will be set to `&http.Client{}` by default. More options are available in the [reddit/reddit-options.go ](reddit/reddit-options.go ) file.
2020-08-02 15:59:25 -04:00
## Examples
< details >
2020-08-26 23:13:34 -04:00
< summary > Submit a comment.< / summary >
2020-08-02 15:59:25 -04:00
```go
2020-08-26 23:13:34 -04:00
comment, _, err := client.Comment.Submit(context.Background(), "t3_postid", "comment body")
if err != nil {
return err
}
fmt.Printf("Comment permalink: %s\n", comment.Permalink)
2020-08-02 15:59:25 -04:00
```
< / details >
< details >
< summary > Upvote a post.< / summary >
```go
_, err := client.Post.Upvote(context.Background(), "t3_postid")
if err != nil {
return err
}
```
< / details >
< details >
2020-08-06 19:26:47 -04:00
< summary > Get r/golang's top 5 posts of all time.< / summary >
2020-08-02 15:59:25 -04:00
```go
2020-08-25 20:55:32 -04:00
result, _, err := client.Subreddit.TopPosts(context.Background(), "golang", & reddit.ListPostOptions{
2020-08-06 19:26:47 -04:00
ListOptions: reddit.ListOptions{
Limit: 5,
},
Time: "all",
})
2020-08-02 15:59:25 -04:00
if err != nil {
return err
}
fmt.Printf("Received %d posts.\n", len(result.Posts))
```
< / details >
More examples are available in the [examples ](examples ) folder.
## Design
2020-08-26 23:13:34 -04:00
The package design is heavily inspired from [Google's GitHub API client ](https://github.com/google/go-github ) and [DigitalOcean's API client ](https://github.com/digitalocean/godo ).
2020-08-02 15:59:25 -04:00
## License
This project is licensed under the MIT License - see the [LICENSE ](LICENSE ) file for details.