TWITTER REST API

Twitter REST API

Twitter là một mạng thông tin và phương tiện giao tiếp cung cấp hơn 200 triệu tweet mỗi ngày. Nền tảng Twitter cung cấp đường truy nhập tới khối dữ liệu đó thông qua Twitter API. Mỗi API biểu thị một khía cạnh của Twitter, và cho phép developer viết và mở rộng ứng dụng của họ theo một cách hoàn toàn mới và sáng tạo. Cần chú ý rằng Twitter API vẫn đang được mở rộng và việc phát triển trên nền tảng Twitter không phải là điều chỉ cần làm một lần.

Twitter dành cho các Website

Twitter cho các Websites (TfW) là một bộ các sản phẩm cho phép người dùng có thể dễ dàng tích hợp các Website với Twitter. TfW thích hợp cho các lập trình viên web những người đang tìm kiếm một giải pháp để nhanh chóng tích hợp những tính năng cơ bản của Twitter vào website của họ. Các tính năng ví dụ như nút Tweet cho phép một người dùng tweet về những thứ anh ta tìm thấy trên website của bạn để chia sẻ tới những người bạn của anh ấy. Bạn của anh ấy nhìn thấy tweet đó, ấn vào đó để tới trang web của bạn, và một số trong các bạn của anh ấy sẽ tweet một nội dung giống như thế cho bạn bè của họ – một vòng lặp tuyệt vời để trang web của bạn được nhiều người biết đến. Cũng giống như thế, tính năng Follow cho phép người dùng có thể nhanh chóng theo dõi tài khoản của bạn trên Twitter. Người dùng đó sẽ nhìn thấy những thay đổi ở tài khoản của bạn trong trang của cô ấy.

REST API

REST API cho phép lập trình viên truy nhập vào một vài core nguyên thuỷ của Twitter bao gồm các timeline, các cập nhật status, và thông tin người dùng. Bạn có thể xây dựng profile của một người dùng: tên của họ, Twitter họ đang dùng, profile avater, và tập hợp những người mà họ đang theo dõi trên Twitter – tất cả chỉ với một vài lời gọi RESTful API. Thêm vào đó, để cho phép truy nhập vào timeline, status, user object thông qua lập trình, API này cung cấp cho lập trình viên rất nhiều những phương thức tích hợp để giao tiếp với Twitter. Qua REST API, người dùng có thể tạo và gửi tweet ngược lại Twitter, trả lời tweet, thích ( chọn favourite) các tweet, retweet lại của người khác và rất nhiều những tính năng khác.

Các phiên bản của Twitter REST API

Hiện Twitter REST API có phiên bản 1 và phiên bản 1.1, tuy nhiên bản 1 không được sử dụng nữa.

Phiên bản gần nhất là REST API 1.1.

Các phương thức của REST API v1.1

Timelines

1. GET statuses/mentions_timeline

Trả về 20 thông tin gần nhất có đề cập tới người dùng ( tweet bao gồm @screen_name của người dùng ) cho người dùng đã đăng nhập. Timeline trả về giống như những thứ bạn thấy khi bạn xem phần metions ở twitter.com. Phương thức này có thể trả về tới 800 tweet.

URL: https://api.twitter.com/1.1/statuses/metions_timeline.json

1. GET statuses/user_timeline

Trả về một tập những Tweet gần đây nhất đăng bởi người dùng được chỉ ra bởi thông số screen_name hoặc user_id. Timelime của người dùng được bảo mật, sẽ chỉ nhận những request từ người dùng đó ( xác nhận bằng đăng nhập ) hoặc một người theo dõi người dùng đó đã được cho quyền xem. Timeline trả về giống như những thứ bạn thấy khi xem profile một người dùng trên twitter.com. Phương thức này có thể trả vời tới 3200 Tweet gần nhất của người dùng.

URL: https://api.twitter.com/1.1/statuses/user_timeline.json

1. GET statuses/home_timeline

Trả về tập hợp những Tweet và Retweet gần nhất được đăng bởi người dùng đăng nhập và những người dùng mà họ đang theo dõi. Home timeline là trung tâm của những tương tác giữa người dùng và dịch vụ Twitter. Có thể lấy được tới 800 tweet từ home timeline. Kết quả trả về dễ thay đổi trong trường hợp user theo dõi nhiều người dùng khác hoặc theo dõi những người dùng thường xuyên tweet.

URL: https://api.twitter.com/1.1/statuses/home_timeline.json

1. GET statuses/retweets_of_me

Trả về những tweet gần nhất được tạo bởi người dùng đăng nhâp hiện tại mà những tweet này đã được retweet bởi những người khác. Timeline này là một tập con của GET statuses/user_timeline của người dùng.

URL: https://api.twitter.com/1.1/statuses/retweets_of_me

Tweets

Tweet là một khối xây dựng cơ bản của Twitter, gồm 140 kí tự cập nhật trạng thái đi cùng với metadata. Mọi người tweet vì nhiều lý do khác nhau và tweet về nhiều các chủ đề.

1. GET statuses/retweets/:id

Trả về tập hợp của 199 retweet gần nhất theo thông số id.

URL: https://api.twitter.com/1.1/statuses/retweets/:id.json

1. GET statuses/show/:id

Trả về một tweet duy nhất, chỉ ra bởi thông số id. Người đăng tweet này cũng sẽ đi kèm cùng với tweet.

URL: https://api.twitter.com/1.1/statuses/show/:id

1. POST statuses/destroy/:id

Xoá một status chỉ ra bởi thông số ID bắt buộc phải có. Người dùng đăng nhập bắt buộc phải là người đăng status đã được chỉ ra. Trả về status đã xoá trong trường hợp thành công.

URL: https://api.twitter.com/1.1/statuses/destroy/:id.json

1. POST statuses/update

Cập nhật trạng thái hiện tại của người dung đăng nhập, có thể nói cách khách là tweeting. Để upload một bức ảnh đi cùng với tweet, sử dụng POST statuses/update_with_media. Với mỗi lần cập nhật, dòng cập nhật sẽ được so sánh với những tweet gần đây của người dùng đăng nhập. Những cập nhật gây ra kết quả trung lặp sẽ bị chặn lại và báo về lỗi 403. Vì vậy người dùng không thể cập nhật những dòng trạng thái giống nhau một cách liên tiếp. Số lượng cập nhật liên tiếp trong một khoảng thời gian nhất định cũng bị giới hạn, do đó người dùng sẽ nhận được lỗi HTTP 403 nếu vượt quá giới hạn này.

URL: https://api.twitter.com/1.1/statuses/update.json

1. POST statuses/retweet/:id

Retweet một tweet nào đó. Trả về tweet nguồn với thông tin retweet được nhúng vào.

URL: https://api.twitter.com/1.1/statuses/retweet/:id

1. POST statuses/update_with_media

Cập nhật trạng thái của người dùng đăng nhập và đính kèm một media để upload. Nói cách khác, nó tạo ra một tweet với một bức ảnh đính kèm. Không giống POST statuses/update, phương thức này yêu cầu dữ liệu raw và được chia làm nhiều phần. POST request Content-Type của bạn cần phải được thiết lập là multipart/form-date với thong số media[].

Dòng tweet có thể đi kèm với URL của media, nhưng sẽ làm giảm số lượng kí tự được cho phép trong dong tweet đó. Nếu URL làm tweet dài hơn 140 kí tự, tweet sẽ bị từ chối và kết quả trả về lỗi 403.

URL: https://api.twitter.com/1.1/statuses/update_with_media.json

1. GET statuses/oembed

Trả về thông tin cho phép tạo ra dạng nhúng của một Tweet trong site của bên thứ ba. Endpoint này cho phép thay đổi (customize) một chút cho dạng hiển thị cuối cùng Tweet được nhúng, cần lưu ý rằng dạng hiển thị của Tweet được đưa ra có thể thay đổi theo thời gian để thích hợp với yêu cầu hiển thị của Twitter. Không nên nghĩ rằng các thông số class hoặc id sẽ giữ nguyên trạng ở kết quả trả về.

URL: https://api.twitter.com/1.1/statuses/oembed.json

1. GET statuses/retweeters/ids

Tra về một tập hợp có thể lên tới 100 ID người dùng mà những người này đã retweet tweet được chỉ ra bởi thong số id. Phương thức này trả về kết quả tương tự như GET statuses/retweets/:id và thay thế phương thức GET statuses/:id/retweeted_by/ids của API phiên bản 1.

URL: https://api.twitter.com/1.1/statuses/retweeters/ids.json

Tìm kiếm

Tìm kiếm các Tweet tương ứng với truy vấn được gửi bởi người dùng của bạn.

1. GET search/tweets

Trả về một tập hợp các Tweet tương ứng truy vấn được gọi. Cần lưu ý rằng Twitter search sẽ không trả về một tập hợp Tweet với cấu trúc hoàn hảo. Không phải tất cả các tweet sẽ được đánh thứ tự và cũng không phải tất cả có thể search được. Ở API phiên bản 1.1, cấu trúc kết quả trả về của API tìm kiếm đã được sửa đổi để trả về những Tweet object giống với những object bạn tìm thấy được ở API và nền tảng REST.

Để tìm hiểu về cách sử dụng Twitter Search một cách hiệu quả nhất, bạn nên xem ở Using the Twitter Search API.

URL: https://api.twitter.com/1.1/search/tweets.json

Streaming

1. POST statuses/filter

Trả về những status công khai đã được lọc qua filter. Nhiều thông số có thể được định rõ để cho phép hầu hết các máy client sử dụng một kết nối tới Streaming API. Cả request GET và POST đều được hỗ trợ. Nhưng request GET với quá nhiều thông số có thể khiến request bị từ chối vì URL quá dài. Sử dụng một POST request để tránh trường hợp URL dài.

Các trường track, follow và location nên được xem xét để ghép vào với nhau bằng mệnh đề OR.

track=foo&follow=1234 trả về những Tweet có “foo” hoặc được tạo bởi người dùng 1234.

Với mức độ truy nhập mặc định cho phép tới 400 từ khoá track, 5000 user id follow và 25 0.1-360 độ đối với địa điểm.

URL: https://stream.twitter.com/1.1/statuses/filter.json

1. GET statuses/sample

Trả về một lượng nhỏ những mẫu ngẫu nhiên của tất cả những status công khai. Những Tweet trả về mặc định thường có khả năng truy nhập giống nhau, vì thế nếu hai client cùng connect tới một endpoint họ sẽ thấy những Tweet giống nhau.

URL: https://stream.twitter.com/1.1/statuses/sample

1. GET statuses/firehose

Endpoint này yêu cầu quyền truy nhập đặc biệt. Trả về tất cả các status công khai. Một lượng nhỏ các ứng dụng yêu cầu cấp độ truy nhập này. Sử dụng kết hợp các nguồn khác và nhiều cấp độ truy nhập một cách sáng tạo có thể đáp ứng được hầu hết các nhu cầu của các ứng dụng.

URL: https://stream.twitter.com/1.1/statuses/firehose

1. GET user

Lấy các message của một người dùng.

URL: https://userstream.twitter.com/1.1/user.json

1. GET site

Lấy message của một tập các người dùng.

URL: https://sitestream.twitter.com/1.1/site.json

Tin nhắn trực tiếp

Tin nhắn trực tiếp là những tin nhắn ngắn, không công khai giữa hai người dùng. Truy nhập tới tin nhắn trực tiếp được quản lý bởi The Application Permission Model.

1. GET direct_messages

Trả về 20 tin nhắn trực tiếp gần nhất được gửi tới người dùng đăng nhập. Bao gồm thông tin chi tiết về người gửi và người nhận. Bạn có thể request tới 200 tin nhắn trực tiếp mỗi lần gọi, và có thể tới cực đại là 800 tin nhắn trực tiếp. Chú ý, phương thức này yêu cầu một access token với quyền RWD (đọc, viết, tin nhắn trực tiếp ).

URL: https://api.twitter.com/1.1/direct_messages.json

Ví dụ : GET https://api.twitter.com/1.1/direct_messages.json?since_id=236436262535&count=1

1. GET direct_messages/sent

Trả về 20 tin nhắn trực tiếp gần nhất được gửi bởi người dùng đăng nhập. Bao gồm thông tin chi tiết về người nhận và người gửi. Bạn có thể request tới 200 tin nhắn trực tiếp mỗi lần gọi, và có thể tới cực đại là 800 tin nhắn trực tiếp. Chú ý, phương thức này yêu cầu một access token với quyền RWD (đọc, viết, tin nhắn trực tiếp ).

URL: https://api.twitter.com/1.1/direct_messages/sent.json

Ví dụ : GET https://api.twitter.com/1.1/direct_messages/sent.json?count=2&since_id=23593272739423389

1. GET direct_message/show

Trả về một tin nhắn trực tiếp duy nhất, chỉ ra bởi id. Giống như request /1.1/direct_messages.format, phương thức này bao gồm object người dùng của người nhận và người gửi. Phương thức này yêu cầu một access token với quyền RWD (đọc, viết, tin nhắn trực tiếp ).

URL: https://api.twitter.com/1.1/direct_messages/show.json

Ví dụ: GET https://api.twitter.com/1.1/direct_messages/show.json?id=2353265234358

1. POST direct_messages/destroy

Xoá tin nhắn trực tiếp được với id cho trước. Người dùng đăng nhập bắt buộc phải là người nhận của tin nhắn đã được chỉ ra. Phương thức này yêu cầu một access token với quyền RWD (đọc, viết, tin nhắn trực tiếp ).

URL: https://api.twitter.com/1.1/direct_messages/destroy.json

Ví dụ: POST https://api.twitter.com/1.1/direct_messages/destroy.json

1. POST direct_messages/new

Gửi một tin nhắn trực tiếp tới người dùng với ID cho trước với người gửi là người dùng đăng nhập. Cần cả thông số người dùng và đoạn tin nhắn và phải là một request POST. Trả về kết quả là tin nhắn được gửi và định dạng request trong trường hợp thành công.

URL: https://api.twitter.com/1.1/direct_messages/new.json

Ví dụ: POST https://api.twitter.com/1.1/direct_messages/new.json

POST Data: text=hello%2C%2Otworld.%20welcome%20to%201.1.%screen_name=theseancook

Bạn bè và những người theo dõi ( follower )

1. GET friendships/no_retweets/ids

Trả về một tập hợp của các user_id mà người dùng đăng nhập không muốn nhận retweet từ những người này. Sử dụng POST friendships/update để thiết lập trạng thái “no retweets” cho những tài khoản của những người dùng trên đối với trang của người dùng hiện tại.

URL: https://api.twitter.com/1.1/friendships/no_retweets/ids.json

1. GET friends/ids

Trả về tập hợp của những ID của những người dùng mà người dùng được nhắc tới đang theo dõi ( có thể nói cách khác là bạn của họ ). Trong trường hợp này, các kết quả được sắp xếp theo thứ tự người dùng được theo dõi trước tới sau – tuy nhiên, cách sắp xếp này còn phụ thuộc vào những sự thay đổi không được báo trước và những vấn đề về tính nhất quán. Các kết quả được trả về trong một nhóm của 5000 ID người dùng mà nhiều trang của kết quả có thể được chuyển tiếp bằng giá trị next_cursor (con trỏ tiếp theo).

Phương thức này đặc biệt mạnh khi được sử dụng trong phép hợp (conjuntion) với GET users/lookup – một phương thức cho phép bạn chuyển user ID thành một object user đầy đủ.

URL: https://api.twitter.com/1.1/friends/ids.json

1. GET followers/ids

Trả về tập hợp những ID của những người dùng đang theo dõi người dùng được chỉ đến. Trong trường hợp này, các kết quả được sắp xếp theo thứ tự người dùng được theo dõi trước tới sau – tuy nhiên, cách sắp xếp này còn phụ thuộc vào những sự thay đổi không được báo trước và những vấn đề về tính nhất quán. Các kết quả được trả về trong một nhóm của 5000 ID người dùng mà nhiều trang của kết quả có thể được chuyển tiếp bằng giá trị next_cursor (con trỏ tiếp theo).

Phương thức này đặc biệt mạnh khi được sử dụng trong phép hợp (conjuntion) với GET users/lookup – một phương thức cho phép bạn chuyển user ID thành một object user đầy đủ.

URL: https://api.twitter.com/1.1/followers/ids.json

1. GET friendships/incoming

Trả về tập hợp của những ID của tất cả những người đang đợi request follow của họ tới người dùng hiện tại được chấp nhận.

URL: https://api.twitter.com/1.1/friendships/incoming.json

1. GET friendships/outgoing

Tra về tập hợp của ID của tất cả những người mà người dùng hiện tại đang chờ request follow gửi tới họ được chấp nhận.

URL: https://api.twitter.com/1.1/friendships/outgoing.format

1. POST friendships/create

Cho phép người dùng hiện tại theo dõi người dùng được chỉ ra bởi ID. Trả về người dùng được theo dõi với format giống request trong trường hợp thành công. Trả về một chuỗi miêu tả tại sao request thất bại trong trường hợp này. Nếu người dùng hiện tại đã là bạn của người dùng được theo dõi, một lỗi HTTP 403 có thể được trả về, tuy nhiên vì lý do hiệu năng bạn có thể nhận được một response 200 OK kể cả khi đã là bạn bè.

Những action trong phương thức này được tạo ra không đồng thời và sự thay đổi sẽ được đồng bộ dần dần.

URL: https://api.twitter.com/1.1/friendships/create.json

1. POST friendships/destroy

Cho người dùng hiện tại không theo dõi người dùng với ID cho trước nữa. Trả về người dùng bị bỏ theo dõi với định dạng giống với request trong trường hợp thành công. Trả về một chuỗi miêu tả tại sao request thất bại trong trường hợp này. Những action trong phương thức này được tạo ra không đồng thời và sự thay đổi sẽ được đồng bộ dần dần.

URL: https://api.twitter.com/1.1/friendships/destroy.json

1. POST friendships/update

Cho phép người dùng hiện tại cho quyền hoặc bỏ quyền retweet và thông báo tới thiết bị từ một người dùng khác.

URL: https://api.twitter.com/1.1/friendships/update.json

1. GET friendships/show

Trả về thông tin chi tiết về liên hệ bạn bè giữa hai người dùng bất kỳ.

URL: https://api.twitter.com/1.1/friendships/show.json

1. GET friends/list

Trả về tập hợp các object người dùng mà người dùng hiện tại đang theo dõi. Kết quả trả về được sắp xếp thứ tự thời gian. Tuy nhiên thứ tự này có thể bị thay đổi. Kết quả trả về theo từng nhóm của 20 người dùng và các nhóm được chia thành các trang, chuyển giữa các trang bằng con trỏ next_cursor.

URL: https://api.twitter.com/1.1/friends/list.json

1. GET followers/list

Trả về tập hợp các object người dùng đang theo dõi người dùng hiện tại. Kết quả trả về được sắp xếp thứ tự thời gian. Tuy nhiên thứ tự này có thể bị thay đổi. Kết quả trả về theo từng nhóm của 20 người dùng và các nhóm được chia thành các trang, chuyển giữa các trang bằng con trỏ next_cursor.

URL: https://api.twitter.com/1.1/followers/list.json

1. GET friendships/lookup

Trả về mối liên hệ của người dùng hiện tại đối với số lượng lên tới 100 người dùng trong danh sách screen_name và user_id được cung cấp.

URL: https://api.twitter.com/1.1/friendships/lookup.json

( to be continue )

Reference

https://dev.twitter.com/docs/api/1.1