#This is for any twitter client developers who want to support twip in their clients. I assume you have full understanding of OAuth and twitter API.

Introduction for Developers

Twip is a twitter API proxy in PHP. The term "API proxy" is borrowed from Birdnest project. Birdnest is another "API proxy" but it can only be setup in python environment. Twip's goal is to be able to setup an "API proxy" in a PHP environment.

Twip is widely used in China, Since GFW blocked twitter. So if you want to help people to have easy access to twitter, or you just want to increase sales in China, please read this page. Any questions, please contact me directly. My email is:

Details

How it works in Basic Auth?

Twitter's REST API uses HTTP to get/post messages from/to twitter. HTTP requests can be easily obtained and redirected by PHP scripts.

Take the old abandoned Basic Auth as an example. If you want to POST a message to twitter, you can do this as follows:

WARNING:THIS EXAMPLE DOESN'T WORK ANYMORE.

curl -u user:password -d "status=playing with cURL and the Twitter API" http://api.twitter.com/1/statuses/update.xml

With PHP's SERVER variable and cURL lib support, one can setup an API proxy and do the same thing as follows:

curl -u user:password -d "status=playing with cURL and the Twitter API" http://example.com/twip_api_proxy/1/statuses/update.xml

So it's simple with Basic Auth. But when it comes to OAuth, things can be a little more complicated.

How it works in OAuth?

OAuth request is more complecated to be obtained and redirected by PHP script.

For example, the Authorization header in request headers is a must in OAuth. But most virtual host providers runs PHP in fastcgi mode so it's hard to get all request headers PHP got. Even the PHP lib provided by OAuth project can only get all request headers in a nasty way.

And OAuth is designed to prevent Man-in-the-Middle Attack. It makes things like API proxy a little harder.

What should I do to support twip?

Twip4 ( in development but already have a working beta version.Please refer to ForUser page in wiki ) works in two different mode, the t ( transparent ) mode and the o ( override ) mode.

Add support for twip using t mode

In t mode, twip just redirects the requests from your client and send it to twitter, without changing anything. In order to get this mode working, you must do as follows:

• Make API proxy URL as a per-account option and users can change it after the account is added. API proxy can be blocked by GFW too, it better to be able to change it.
• Use https://api.twitter.com/ when generating the signature. Some XAuth API requires https, and it's hard to determing if https is needed, so the most convenient way is to use https://api.twitter.com/ to generate all signatures.
• Send HTTP requests to API proxy if users choose to,even you generated the signature using https://api.twitter.com/. Many virtual hosts doesn't support SSL certificates.
• Use twip's base_url instead of https://api.twitter.com/ , NOT https://api.twitter.com/1/. If an API proxy's URL is: http://example.com/twip_api_proxy/ , and you want to call users/show/yegle.json, send request to http://example.com/twip_api_proxy/1/users/show/yegle.json, not http://example.com/twip_api_proxy/users/show/yegle.json
• Add source=YourAppName in your requests' query string

Add support for twip using o mode

This is not recommended for client author, since the source of the tweet would be user's own source from http://twitter.com/apps

But if you think the above instructions is hard to understand or hard to implement, you can do as follows to get twip working in o mode.

The o in o mode means override. That is: regardless client's requests contain OAuth part or not, twip re-sign this request using twip's OAuth Consumer Key/Secret.

So all you need to do is:

1. add source=YourAppName in your requests' query string
2. add an option so users can change the API root to twip

That's all. Twip will do the rest