You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.,
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.,
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:
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:
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.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
-
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:
Twitter API v2 issues
errors
in the response body/2/openapi.json
returnstext/html
instead ofapplication/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 ofincludes
,meta
, anderrors
elements. Thedata
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 tonew
for the various response types. E.g.,This works well enough. The response objects are effectively defined with:
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.,
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
becomesfind_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.:
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:instead of:
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: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.
Beta Was this translation helpful? Give feedback.
All reactions