twittergo

package module
v0.0.0-...-48e7d14 Latest Latest
Warning

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

 Go to latest Published: Aug 22, 2017 License: Apache-2.0 Imports: 16 Imported by: 0

README

twittergo

This project implements a Go client library for the Twitter APIs. This library supports version 1.1 of Twitter's API and application-only auth.

The goal of this project is to provide a thin veneer over my oauth1a library in order to simplify access to Twitter's APIs from Go. Where possible, I've tried to defer to native objects (use of http requests for example). Additionally, responses could be parsed directly as JSON, but some wrapper types have been defined in order to provide some convenience methods for accessing data.

Build Status

Installing

Run

go get github.com/kurrik/twittergo

Include in your source:

import "github.com/kurrik/twittergo"

Godoc

See http://godoc.org/github.com/kurrik/twittergo

Using

I have moved all of the examples to the https://github.com/kurrik/twittergo-examples project in order to make this library easier to import. Please reference that project for ways to address specific use cases.

The simplest example in the twittergo-examples project is probably verify_credentials. This calls an endpoint which will return the current user if the request is signed correctly.

The example starts by loading credentials, which can be done in many ways. The example implements a LoadCredentials which looks for the CREDENTIALS file mentioned above:

var (
	err    error
	client *twittergo.Client
	req    *http.Request
	resp   *twittergo.APIResponse
	user   *twittergo.User
)
client, err = LoadCredentials()
if err != nil {
	fmt.Printf("Could not parse CREDENTIALS file: %v\n", err)
	os.Exit(1)
}

Then, a standard http request is created to a /1.1/ endpoint:

req, err = http.NewRequest("GET", "/1.1/account/verify_credentials.json", nil)
if err != nil {
	fmt.Printf("Could not parse request: %v\n", err)
	os.Exit(1)
}

The client object handles sending the request:

resp, err = client.SendRequest(req)
if err != nil {
	fmt.Printf("Could not send request: %v\n", err)
	os.Exit(1)
}

The response object has some convenience methods for checking rate limits, etc:

if resp.HasRateLimit() {
	fmt.Printf("Rate limit:           %v\n", resp.RateLimit())
	fmt.Printf("Rate limit remaining: %v\n", resp.RateLimitRemaining())
	fmt.Printf("Rate limit reset:     %v\n", resp.RateLimitReset())
} else {
	fmt.Printf("Could not parse rate limit from response.\n")
}

Finally, if the response format is known, the library provides some standard objects which make parsing response data easier:

user = &twittergo.User{}
err = resp.Parse(user)
if err != nil {
	fmt.Printf("Problem parsing response: %v\n", err)
	os.Exit(1)
}
fmt.Printf("ID:                   %v\n", user.Id())
fmt.Printf("Name:                 %v\n", user.Name())

Error handling

Errors are returned by most methods as is Golang convention. However, these errors may sometimes be cast into twittergo.ResponseError, twittergo.Errors or twittergo.RateLimitError structs which will provide additional information.

To check for rate limiting or other types of server errors, attempt to cast any errors returned by the APIResponse.Parse method.

resp, err = client.SendRequest(req)
if err != nil {
	fmt.Printf("Could not send request: %v\n", err)
	os.Exit(1)
}
tweet = &twittergo.Tweet{}
err = resp.Parse(tweet)
if err != nil {
	if rle, ok := err.(twittergo.RateLimitError); ok {
		fmt.Printf("Rate limited, reset at %v\n", rle.Reset)
	} else if errs, ok := err.(twittergo.Errors); ok {
		for i, val := range errs.Errors() {
			fmt.Printf("Error #%v - ", i + 1)
			fmt.Printf("Code: %v ", val.Code())
			fmt.Printf("Msg: %v\n", val.Message())
		}
	} else {
		fmt.Printf("Problem parsing response: %v\n", err)
	}
	os.Exit(1)
}

The previous snippet would print the following if a user attempted to Tweet the same text twice in a row:

Error #1 - Code: 187 Msg: Status is a duplicate

Rate limit errors are pretty easy to use. They're a simple struct containing what the limit for the request was, how many were remaining (should be 0) and when the limiting resets:

type RateLimitError struct {
	Limit     uint32
	Remaining uint32
	Reset     time.Time
}

The Errors type is a little more complicated, as it may return one or more server side errors. It is possible to cast one to a string using the standard Error method, but if you need to handle individual errors, iterate over the slice returned by Errors (plural) instead:

for i, val := range errs.Errors() {
	fmt.Printf("Error #%v - ", i + 1)
	fmt.Printf("Code: %v ", val.Code())
	fmt.Printf("Msg: %v\n", val.Message())
}

Each of those errors has a Code and a Message method, which return values and strings corresponding to those listed in the "Error codes" section of this page: https://dev.twitter.com/docs/error-codes-responses

Application-only auth

If no user credentials are set, then the library falls back to attempting to authenticate with application-only auth, as described here: https://dev.twitter.com/docs/auth/application-only-auth

If you want to obtain an access token for later use, create a client with no user credentials.

config := &oauth1a.ClientConfig{
	ConsumerKey:    "consumer_key",
	ConsumerSecret: "consumer_secret",
}
client = twittergo.NewClient(config, nil)
if err := c.FetchAppToken(); err != nil {
	// Handle error ...
}
token := c.GetAppToken()
// ... Save token in data store

To restore a previously obtained token, just call SetAppToken():

// Get token from data store ...
c.SetAppToken(token)

Saving and restoring the token isn't necessary if you keep the client in memory, though. If you just create a client without any user credentials, calls to SendRequest will automatically fetch and persist the app token in memory. See search_app_auth/main.go for an example of this.

Google App Engine

This library works with Google App Engine's Go runtime but requires slight modification to fall back on the urlfetch package for http transport.

After creating a Client, replace its HttpClient with an instance of urlfetch.Client:

var (
    r      *http.Request
    config *oauth1a.ClientConfig
    user   *oauth1a.UserConfig
)
...
ctx = appengine.NewContext(r)
c = twittergo.NewClient(config, user)
c.HttpClient = urlfetch.Client(ctx)

For a comprehensive example, see user_timeline_appengine

Custom models

The twittergo library comes with some standard models for structures like Tweets and Timelines, but you are not required to use them. Pass any struct which will deserialize from a Twitter API response to APIResponse.Parse:

type CustomTweet struct {
    CustomID   string `json:"id_str"`
    CustomText string `json:"text"`
}
...

req, err = http.NewRequest("GET", url, nil)
...
resp, err = client.SendRequest(req)
customTweet = &CustomTweet{}
err = resp.Parse(customTweet)
...

For complete code, see the custom_struct example.

Debugging

To see what requests are being issued by the library, set up an HTTP proxy such as Charles Proxy and then set the following environment variable:

export HTTP_PROXY=http://localhost:8888

Because Go will reject HTTPS requests through a proxy, you'll need to set the following for any HTTPS endpoints:

export TLS_INSECURE=1

Make sure not to use this in production!

Documentation

Overview

Implements a Twitter client library in Go.

Index

Constants

View Source 
const (
	H_LIMIT              = "X-Rate-Limit-Limit"
	H_LIMIT_REMAIN       = "X-Rate-Limit-Remaining"
	H_LIMIT_RESET        = "X-Rate-Limit-Reset"
	H_MEDIA_LIMIT        = "X-MediaRateLimit-Limit"
	H_MEDIA_LIMIT_REMAIN = "X-MediaRateLimit-Remaining"
	H_MEDIA_LIMIT_RESET  = "X-MediaRateLimit-Reset"
)
View Source 
const (
	STATUS_OK           = 200
	STATUS_CREATED      = 201
	STATUS_ACCEPTED     = 202
	STATUS_NO_CONTENT   = 204
	STATUS_INVALID      = 400
	STATUS_UNAUTHORIZED = 401
	STATUS_FORBIDDEN    = 403
	STATUS_NOTFOUND     = 404
	STATUS_LIMIT        = 429
	STATUS_GATEWAY      = 502
)

Variables

This section is empty.

Functions

This section is empty.

Types

type APIResponse 

type APIResponse http.Response

APIResponse provides methods for retrieving information from the HTTP headers in a Twitter API response.

func (APIResponse) HasMediaRateLimit 

func (r APIResponse) HasMediaRateLimit() bool

func (APIResponse) HasRateLimit 

func (r APIResponse) HasRateLimit() bool

func (APIResponse) MediaRateLimit 

func (r APIResponse) MediaRateLimit() uint32

func (APIResponse) MediaRateLimitRemaining 

func (r APIResponse) MediaRateLimitRemaining() uint32

func (APIResponse) MediaRateLimitReset 

func (r APIResponse) MediaRateLimitReset() time.Time

func (APIResponse) Parse 

func (r APIResponse) Parse(out interface{}) (err error)

Parse unmarshals a JSON encoded HTTP response into the supplied interface, with handling for the various kinds of errors the Twitter API can return.

The returned error may be of the type Errors, RateLimitError, ResponseError, or an error returned from io.Reader.Read().

func (APIResponse) RateLimit 

func (r APIResponse) RateLimit() uint32

func (APIResponse) RateLimitRemaining 

func (r APIResponse) RateLimitRemaining() uint32

func (APIResponse) RateLimitReset 

func (r APIResponse) RateLimitReset() time.Time

func (APIResponse) ReadBody 

func (r APIResponse) ReadBody() string

ReadBody returns the body of the response as a string. Only one of ReadBody and Parse may be called on a given APIResponse.

type BearerToken 

type BearerToken struct {
	AccessToken string
}

type Client 

type Client struct {
	Host       string
	OAuth      *oauth1a.Service
	User       *oauth1a.UserConfig
	AppToken   *BearerToken
	HttpClient *http.Client
}

Implements a Twitter client.

func NewClient 

func NewClient(config *oauth1a.ClientConfig, user *oauth1a.UserConfig) *Client

Creates a new Twitter client with the supplied OAuth configuration. Supports the use of HTTP proxies through the $HTTP_PROXY env var. For example: 

export HTTP_PROXY=http://localhost:8888

When using a proxy, disable TLS certificate verification with the following: 

export TLS_INSECURE=1

func (*Client) FetchAppToken 

func (c *Client) FetchAppToken() (err error)

Requests a new app auth bearer token and stores it.

func (*Client) GetAppToken 

func (c *Client) GetAppToken() string

Returns the current app-only auth token or an empty string. Must call FetchAppToken to populate this value before getting it. You may call SetAppToken with the value returned by this call in order to restore a previously-fetched bearer token to use.

func (*Client) SendRequest 

func (c *Client) SendRequest(req *http.Request) (resp *APIResponse, err error)

Sends a HTTP request through this instance's HTTP client.

func (*Client) SetAppToken 

func (c *Client) SetAppToken(token string)

Sets the app-only auth token to the specified string.

func (*Client) SetUser 

func (c *Client) SetUser(user *oauth1a.UserConfig)

Changes the user authorization credentials for this client.

func (*Client) Sign 

func (c *Client) Sign(req *http.Request) (err error)

Signs the request with app-only auth, fetching a bearer token if needed.

type CursoredLists 

type CursoredLists map[string]interface{}

func (CursoredLists) Lists 

func (cl CursoredLists) Lists() Lists

func (CursoredLists) NextCursorStr 

func (cl CursoredLists) NextCursorStr() string

func (CursoredLists) PreviousCursorStr 

func (cl CursoredLists) PreviousCursorStr() string

type Error 

type Error map[string]interface{}

func (Error) Code 

func (e Error) Code() int64

func (Error) Error 

func (e Error) Error() string

func (Error) Message 

func (e Error) Message() string

type Errors 

type Errors map[string]interface{}

func (Errors) Error 

func (e Errors) Error() string

func (Errors) Errors 

func (e Errors) Errors() []Error

func (Errors) String 

func (e Errors) String() string

type List 

type List map[string]interface{}

A List!

func (List) Id 

func (l List) Id() (id uint64)

func (List) IdStr 

func (l List) IdStr() string

func (List) MemberCount 

func (l List) MemberCount() int64

func (List) Mode 

func (l List) Mode() string

func (List) Name 

func (l List) Name() string

func (List) Slug 

func (l List) Slug() string

func (List) SubscriberCount 

func (l List) SubscriberCount() int64

func (List) User 

func (l List) User() User

type Lists 

type Lists []List

It's a less structured list of Lists!

type MediaResponse 

type MediaResponse map[string]interface{}

Response for media upload requests.

func (MediaResponse) ExpiresAfterSecs 

func (r MediaResponse) ExpiresAfterSecs() int32

func (MediaResponse) MediaId 

func (r MediaResponse) MediaId() int64

func (MediaResponse) Size 

func (r MediaResponse) Size() int64

func (MediaResponse) Video 

func (r MediaResponse) Video() VideoUpload

type RateLimitError 

type RateLimitError struct {
	Limit     uint32
	Remaining uint32
	Reset     time.Time
}

RateLimitError is returned from SendRequest when a rate limit is encountered.

func (RateLimitError) Error 

func (e RateLimitError) Error() string

func (RateLimitError) HasRateLimit 

func (e RateLimitError) HasRateLimit() bool

func (RateLimitError) RateLimit 

func (e RateLimitError) RateLimit() uint32

func (RateLimitError) RateLimitRemaining 

func (e RateLimitError) RateLimitRemaining() uint32

func (RateLimitError) RateLimitReset 

func (e RateLimitError) RateLimitReset() time.Time

type RateLimitResponse 

type RateLimitResponse interface {
	// HasRateLimit returns false if the ratelimiting information is
	// optional and missing.
	HasRateLimit() bool
	// RateLimit returns the requests per time period capacity of the
	// limit.
	RateLimit() uint32
	// RateLimitRemaining returns how many requests are still available
	// in the current time period.
	RateLimitRemaining() uint32
	// RateLimitReset returns when the rate limit will reset.
	RateLimitReset() time.Time
}

RateLimitResponse is implemented by both RateLimitError and APIResponse.

type ResponseError 

type ResponseError struct {
	Body string
	Code int
}

Error returned if there was an issue parsing the response body.

func NewResponseError 

func NewResponseError(code int, body string) ResponseError

func (ResponseError) Error 

func (e ResponseError) Error() string

type SearchResults 

type SearchResults map[string]interface{}

It's a structured list of Tweets!

func (SearchResults) NextQuery 

func (sr SearchResults) NextQuery() (val url.Values, err error)

func (SearchResults) SearchMetadata 

func (sr SearchResults) SearchMetadata() map[string]interface{}

func (SearchResults) Statuses 

func (sr SearchResults) Statuses() []Tweet

type Timeline 

type Timeline []Tweet

It's a less structured list of Tweets!

type Tweet 

type Tweet map[string]interface{}

It's a Tweet! (Adorably referred to by the API as a "status").

func (Tweet) CreatedAt 

func (t Tweet) CreatedAt() (out time.Time)

func (Tweet) FullText 

func (t Tweet) FullText() string

func (Tweet) Id 

func (t Tweet) Id() (id uint64)

func (Tweet) IdStr 

func (t Tweet) IdStr() string

func (Tweet) Language 

func (t Tweet) Language() string

func (Tweet) Text 

func (t Tweet) Text() string

func (Tweet) User 

func (t Tweet) User() User

type User 

type User map[string]interface{}

It's a user!

func (User) Id 

func (u User) Id() uint64

func (User) IdStr 

func (u User) IdStr() string

func (User) Name 

func (u User) Name() string

func (User) ScreenName 

func (u User) ScreenName() string

type VideoUpload 

type VideoUpload map[string]interface{}

Nested response structure for video uploads.

func (VideoUpload) Type 

func (v VideoUpload) Type() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.