Twitter API v2 Support

[semifor]

Twitter API v2 is rolling out

Twitter API v2 Early Access is available and there's preliminary support for it in the api-v2 branch. This code isn't ready for a CPAN release or use in production, yet, though I may do a TRIAL release, soon.

You're welcome to use the api-v2 branch to gain early access to the beta, discuss the design concepts, and review the code.

I'll likely not do a full release until:

• The Twitter API stabilizes
• I've finalized the design
• I've written documentation and tests

Twitter API v2 issues

• Currently, the Open API Spec does not validate (it's missing definitions for the response schemas for the manage likes endpoints).
• There are inconsistencies and missing information in the spec.
• Error handling is inconsistent:
  • some error conditions return 200 OK with errors in the response body
  • some conditions return incorrect HTTP response status codes, e.g., 400 instead of 403
  • some conditions return misleading errors, e.g., 200 OK with "resource not found" in response body when the authed user's account is locked
• Some responses have the wrong Content-Type header, e.g., /2/openapi.json returns text/html instead of application/json.

Design decisions

I'm trying to wrap Twitter API v2 responses in objects that have accessors for expected fields. Successful responses return a JSON object with a data element and may contain one or more of includes, meta, and errors elements. The data element may be a JSON object for a single response (a User or Tweet), or an array of JSON objects (Users or Tweets). I'm currently instantiating response by passing the decoded JSON directly to new for the various response types. E.g.,

    my $api_response = Twitter::API::V2::Response::SingleUserResponse->new($decode_json_response);

This works well enough. The response objects are effectively defined with:

    has data => ...;
    has includes => ...;
    has meta => ...,
    has errors => ...,

But it might be better instantiate the response types with ->new(response => $decoded_json_response). That way, you'll always have access to the raw, unblessed, decoded response body Twitter sent. I don't like the deeper nesting, though, if it isn't necessary.

Responses that return an array of results can be treated as arrays. E.g.,

    my $response = $client->tweets_search_recent_search({ query => 'perl' });
    say $_->decoded_text for @$response;

    my $tweets = Twitter::API::V2::Tweet::Array->new;
    push @$tweets, $r;

    my $next_page = $api->tweets_search_recent({
        query => 'perl',
        next_token => $response->next_token,
    });
    push @$tweets, $next_page;

The API spec specifies operation ID's for each path/http-method pair in camel case. I hate camel case. So, I've transformed Twitter's operation IDs to snake case. So, findUserById becomes find_user_by_id.

I intended to strictly use these transformed operation IDs as method names, letting the spec determine them. In fact, I'd hoped to be able to support v2 generating classes and methods directly from the spec. Until the spec is stable and validates, that's not practical. And there are some methods I've provided instead of using the semantics Twitter provides in the spec. E.g.:

• follow
• unfollow
• block
• unblock
• like
• unlike

These methods, defined in Twitter::API::Trait::APIv2, take just a single argument, the target user ID or tweet ID. They extract the authenticated user ID from the OAuth access token. So, you can simply call:

    my $response = $client->follow($target_user_id);

instead of:

    my $response = $client->users_id_following({
        id => $authed_user_id,
        -to_json => { target_user_id => $target_user_id },
    });

Low-level calls

You don't have to use the convenience methods supplied by Twitter::API::Trait::APIv2. You can call the endpoints directly by using Twitter::API's get, post, put, and delete handlers directly. You'll get the decode JSON responses rather than Response objects. You can all use these lower-level call semantics to access endpoints Twitter adds before there are corresponding endpoints added to Twitter::API. E.g., rather than calling find_user_by_username, you can call:

    my $r = $client->get("users/by/username/$username", \%options);

Just provide the path (less the leading /2/, with path agreements expanded and whatever parameters you require in %options. If the endpoint expects a JSON body argument, pass it with the -to_json option.

Join the discussion

If you're using Twitter::API and need API v2 support, let me know what you think of the work-in-progress. Let me know if I'm making any design mistakes so I can make corrections and adjustments before a CPAN release.