creachadair / twitter

A Go client for the Twitter v2 API (in development).

twitter

Note: It is no longer practical or worthwhile for me to continue work on this library, as Twitter now charges $100 per month for minimal API access. I have therefore archived the repository.

This repository provides Go package that implements an experimental client for the Twitter API v2. It is no longer under active development.

This was an experiment, and is not ready for production use. In particular, test coverage is not nearly as good as it should be. There are replay tests using responses captured from the production service, but a lot of invariants remain unverified.

The documentation could also use more work. All the packages and exported types have doc comments, but working examples are lacking. Normal test-based examples are tricky because there is not (as far as I know) a good test double for the API.

API Index

Here is the current status of v2 API endpoint implementations.

Edits

• DELETE 2/tweets/:id
• PUT 2/tweets/:id/hidden
• POST 2/users/:id/blocking
• DELETE 2/users/:id/blocking/:other
• POST 2/users/:id/bookmarks
• DELETE 2/users/:id/bookmarks/:tid
• POST 2/users/:id/following
• DELETE 2/users/:id/following/:other
• POST 2/users/:id/likes
• DELETE 2/users/:id/likes/:tid
• POST 2/users/:id/muting
• DELETE 2/users/:id/muting/:other
• POST 2/users/:id/pinned_lists
• DELETE 2/users/:id/pinned_lists/:lid
• POST 2/users/:id/retweets
• DELETE 2/users/:id/retweets/:tid

Lists

• GET 2/lists
• POST 2/lists
• DELETE 2/lists/:id
• PUT 2/lists/:id
• GET 2/lists/:id/followers
• GET 2/lists/:id/members
• POST 2/lists/:id/members
• DELETE 2/lists/:id/members/:userid
• GET 2/lists/:id/tweets
• GET 2/lists/:id/pinned_lists

Rules

• GET 2/tweets/search/stream/rules
• POST 2/tweets/search/stream/rules
• POST 2/tweets/search/stream/rules, dry_run=true

Tweets

• GET 2/tweets
• POST 2/tweets
• GET 2/tweets/:id/liking_users
• GET 2/tweets/:id/quote_tweets
• GET 2/tweets/count/all (requires academic access)
• GET 2/tweets/count/recent
• GET 2/tweets/sample/stream
• GET 2/tweets/search/all (requires academic access)
• GET 2/tweets/search/recent
• GET 2/tweets/search/stream

Users

• GET 2/users
• GET 2/users/:id/blocking
• GET 2/users/:id/bookmarks
• GET 2/users/:id/followed_lists
• GET 2/users/:id/followers
• GET 2/users/:id/following
• GET 2/users/:id/liked_tweets
• GET 2/users/:id/list_memberships
• GET 2/users/:id/mentions
• GET 2/users/:id/muting
• GET 2/users/:id/owned_lists
• GET 2/users/:id/retweeted_by
• GET 2/users/:id/tweets
• GET 2/users/by
• GET 2/users/me

twitter's Issues

Parse and report JSON error messages when requests fail

On error, the v2 API reports a JSON text along with the status code. The exact format isn't clear, but it has the general shape:

{
  "errors": [ {"message": "you done broke it", "code": 45} ]
}

The response codes are defined here: https://developer.twitter.com/en/docs/response-codes. In the wild, though, the format varies quite a bit. Sometimes the top-level message has status and details as additional keys:

{
  "errors": [
    {
      "parameters": {
        "expansions": [
          "3"
        ]
      },
      "message": "The `expansions` query parameter value [3] is not one of [pinned_tweet_id]"
    }
  ],
  "title": "Invalid Request",
  "detail": "One or more parameters to your request was invalid.",
  "type": "https://api.twitter.com/2/problems/invalid-request"
}

Other times everything is inside the array:

{
  "errors": [
    {
      "detail": "Could not find user with username: [fal27f87fse].",
      "title": "Not Found Error",
      "resource_type": "user",
      "parameter": "username",
      "value": "fal27f87fse",
      "type": "https://api.twitter.com/2/problems/resource-not-found"
    }
  ]
}

The API docs don't appear to document the expected formats. Figure out some reasonable way to interpret these values, and attach them to error values.

MediaFields is missing URL

Hi. Thanks for the nice library!

MediaFields is missing URL. We have to make a custom struct to get the media url.
I would be happy to see this fixed.

type MediaFields struct {
	URL bool
}

Add support for the streaming search API

See https://developer.twitter.com/en/docs/twitter-api/tweets/filtered-stream/api-reference/get-tweets-search-stream et seq.

Streaming will require another client method to read from the body progressively. The caller will probably have to plumb in a callback, and we'll have to do something to handle cancellation. Provisionally: When ctx ends, force-close the body to unblock the reader. I'm not sure if that's racy, or if it will trigger a panic, so do some experiments.

Add support for the sampling API

See: https://developer.twitter.com/en/docs/twitter-api/tweets/sampled-stream/api-reference/get-tweets-sample-stream