Twitter Fan Club: DocsApi

Docs Api

info: cette page est réservé aux geeks et recense ce qui a trait à l'API officielle et aux documentations non officielles. Le TwitterFanClub ne pourra être tenu responsable de rien sur l'utilisation de ces informations restant à vérifier. Seul le lien du wiki canonique fait référence.

Les docs de l'API officielle sont posées sur

ici. Regardez aussi le

Google Group de discussion de développement Twitter

index
Docs API Non officielles

Commandes Publiquement Disponibles

ligne de temps publique (public timeline)

Authorization

Autorisation Basique

Login Autorisation

Commandes Autorisées

<code>user timeline</code>

<code>friends timeline</code>

<code>friends</code>

<code>followers</code>

<code>update</code>

<code>account settings</code>

Types de Réponses

Réponses Status

Réponses utilisateurs

Titres requêtes

Conventions

Docs API Non officielles

Publicly Available Commands
- public_timeline
Authorization
- Basic Authorization
- Login Authorization
Authorized Commands
Response Types
- Status Responses
- User Responses
Request Headers
Conventions

Commandes Publiquement Disponibles

ligne de temps publique (public timeline)

La ligne de temps publique peut être retrouvée sour JSON, XML, RSS et ATOM à partir des URLs suivantes :

Ce fail renverra toujours (actuellement) les 20 derniers billets. Néanmoins la suggestion d'un paramètre 'count' a été soulevée. par ex :

http://twitter.com/statuses/public_timeline.xml?count=5

Response type:** status

Authorization

Il existe actuellement deux options pour l'autorisation :

Basic Authorization
Login Authorization et gestionnaire cookie de session

Les deux ont besoin de bonnaître le nomutilisateur de l'utilisateur et son mot de passe.

Autorisation Basique

L'autorisation basique est produire via n'importe quelle méthode requise par votre librairie. Ce pourrait être l'utilisation simple d'une URL telle que :

http://username:password@twitter.com/statuses/user_timeline.xml

Toute autre implémentation d'autorisation basique devrait référer aux librairies WWW de votre langage de programmation.

Response type:** N/A - This auth type is used with any command. A 401 status indicates a failed auth.

Login Autorisation

Avertissement : Ce n'est pas une commande officielle API. Vous recevrez une réponse text/html. Vous aurez besoin de parser cela pour déterminer le succès/échec. Il n'existe aucune garantie que Twitter

ne changera pas le contenu de la page retournée.

Si vous préférez, vous pouvez utiliser un gestionnaire de cookie pour connecter via l'autorisation du site web. Envoyez une requête POST à http://twitter.com/login avec les ensembles de paramètres appropriés '<code>nomutilisateur ou email</code>' et '<code>motdepasse</code>'. Les titres de la réponse comprendront un cookie '<code>_twitter_session</code>' cookie. Présentez cela sur toutes les futures requêtes.

Response type:** html

Commandes Autorisées

Ce commandes sont uniquement disponibles pour les utilisateurs qui se sont connectés comme au-dessus

<code>user timeline</code>

This command returns the authorized user's timeline. The following URLs require no extra parameters:

Response type:** status

<code>friends timeline</code>

This command returns the authorized user's friends timeline (friends include the authorized user). The following URLs require no extra parameters:

Response type:** status

<code>friends</code>

This command returns the authorized user and their friends' current status. *Not* a timeline, just the latest entry:

http://twitter.com/statuses/friends.json
http://twitter.com/statuses/friends.xml
-<raw> http://twitter.com/statuses/friends.rss</raw>-
-<raw> http://twitter.com/statuses/friends.atom</raw>-

Response type:** user

NOTE: 2007-03-21: This appears not to be working for RSS or ATOM

<code>followers</code>

This command returns the authorized user's followers' current status. Once again, *not* a timeline, just the latest entry:

http://twitter.com/statuses/friends.json
http://twitter.com/statuses/friends.xml
-<raw> http://twitter.com/statuses/friends.rss</raw>-
-<raw> http://twitter.com/statuses/friends.atom</raw>-

Response type:** user

NOTE: 2007-03-21: This appears not to be working for RSS or ATOM

<code>update</code>

This command allow you to set the authorized user's status. Send a POST request to the following URLs with the '<code>status</code>' parameter set to the new status. Don't forget to URL-encode the status if you library doesn't do it for you.

http://twitter.com/statuses/update.json
http://twitter.com/statuses/update.xml

Response type:** null

<code>account settings</code>

NOTE: This is not an official API command. You will receive a text/html response. You will need to parse that to determine success/failure. There is no guarantee Twitter

will not change the content of the returned page.

This command allows you to set various account settings for the authorized user. Send a POST to the following URL:

http://twitter.com/account/settings

The following parameter names should be self explanatory. Don't forget to URL Encode both the parameter name and value if your library doesn't handle that for you automatically.

<code><raw>user[name]</raw></code> -- Only letters, numbers and underscores (_) are allowed
<code><raw>user[email]</raw></code>
<code><raw>user[time zone]</raw></code> -- See the website source for a list of accepted values
<code><raw>user[url]</raw></code>
<code><raw>user[description]</raw></code> -- Up to 160 characters only.
<code><raw>user[location]</raw></code>
<code><raw>user[protected]</raw></code> -- 1 or 0

Response type:** html

Types de Réponses

Réponses Status

Ce réponse sont en réponse pour les requêtes de type timeline.

Champs renvoyés :

Field Path Data format Example

created_at HTTP Format date Tue Mar 13 00:12:41 +0000 2007

text Up to 160 characters of utf8 Creating this table

id Integer 123

user.name Up to 40 characters of utf8 Rick Measham

user.description Up to 160 characters of utf8 Perl and Javascript Developer

user.location Up to 30 characters of utf8 Melbourne, Australia

user.screen_name Up to 15 characters from: A-Z a-z 0-9 and _ RickMeasham

user.url Up to 100 characters of utf8 http://rick.measham.id.au/

user.id Integer 1050881

(Note that the XML looks like: <code><statuses><status><created at> ... </created_at> ... </status><statuses></code>

Field Path	Data format	Example
`created_at`	HTTP Format date	Tue Mar 13 00:12:41 +0000 2007
`text`	Up to 160 characters of utf8	Creating this table
`id`	Integer	123
`user.name`	Up to 40 characters of utf8	Rick Measham
`user.description`	Up to 160 characters of utf8	Perl and Javascript Developer
`user.location`	Up to 30 characters of utf8	Melbourne, Australia
`user.screen_name`	Up to 15 characters from: A-Z a-z 0-9 and _	RickMeasham
`user.url`	Up to 100 characters of utf8	http://rick.measham.id.au/
`user.id`	Integer	1050881

Réponses utilisateurs

These responses are in reply to requests that return user information such as <code>friends</code> and <code>followers</code>.

Fields returned:

Field Path Data format Example

id Integer 1050881

name Up to 40 characters of utf8 Rick Measham

location Up to 30 characters of utf8 Melbourne, Australia

description Up to 160 characters of utf8 Perl and Javascript Developer

profile_image_url Valid URL at twitter.com (the query string appears to be a random number to force a reload each time) http://static.twitter.com//system/user/profile_image/1050881/normal/rickm.png?1173740203

url Up to 100 characters of utf8 http://rick.measham.id.au/

status.created_at HTTP Format date Tue Mar 13 00:12:41 +0000 2007

status.id Integer 123

status.text Up to 160 characters of utf8 Creating this table

Field Path	Data format	Example
`id`	Integer	1050881
`name`	Up to 40 characters of utf8	Rick Measham
`location`	Up to 30 characters of utf8	Melbourne, Australia
`description`	Up to 160 characters of utf8	Perl and Javascript Developer
`profile_image_url`	Valid URL at twitter.com (the query string appears to be a random number to force a reload each time)	http://static.twitter.com//system/user/profile_image/1050881/normal/rickm.png?1173740203
`url`	Up to 100 characters of utf8	http://rick.measham.id.au/
`status.created_at`	HTTP Format date	Tue Mar 13 00:12:41 +0000 2007
`status.id`	Integer	123
`status.text`	Up to 160 characters of utf8	Creating this table

(Note that the XML looks like: <code><users><user><created at> ... </created_at> ... </user><users></code>

Titres requêtes

These headers are currently considered a de facto standard. So they may change. Don't blame me if you have to change your code later on, but on 2007-03-21, Alex Payne (from Twitter

) said: Please do start sending headers to us. It'll be most helpful for planning our capacity.

Rick Measham (that's me!) then suggested the following headers, to which Alex replied: Those X headers are exactly along the lines of what I was thinking. Thanks for setting a sane de-facto standard!

The following request header **should** be used when making the above calls:

<code>X-Twitter -Client: <raw>[The 'brand name' of your client]</raw></code>

The following request headers **can** be used when making the above calls:

<code>X-Twitter -Client-Version: <raw>[The version number]</raw></code>
<code>X-Twitter -Client-URL: <raw>[URL of your client's meta information for publication in some future directory. See below]</raw></code>

The URL **must** point to an XML document something like the following: <blockquote>

<client>
	<name>GoogleGadget</name>
	<version>2.01</version>
	<author>
		<name>Rick Measham</name>
		<email>google@twitter.isite.net.au</email>
		<twitter>RickMeasham</twitter>
	</author>
	<url>http://twitter.isite.net.au</url>
	<twitter>GoogleGadget</twitter>
	<description><[CDATA[
		The Twitter Google Gadget brings all the fun of twitter to your Google personalised homepage.
		<a href="http://fusion.google.com/add?feedurl=http%3A//twitter.isite.net.au/twitter.xml"><img src="http://buttons.googlesyndication.com/fusion/add.gif" width="104" height="17" border="0" alt="Add to Google"></a>
	]]>
</client>

</blockquote>

NOTE:** I expect this XML may change .. this was a quick hack. Join the developers list and chime in if you want to comment.

Conventions

Les termes suivants sont utilisés dans ce document pour signifier les exigences de l'API. Ceux en gras ne s'appliquent uniquement que quand ils sont affichés en gras. (Ils sont basés sur la section 1.2 de la [1])

**must**, or the adjective REQUIRED, means that the definition is an absolute requirement of the specification.
**must not** that the definition is an absolute prohibition of the specification.
**should** means that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications **must** be understood and carefully weighed before choosing a different course.
**should not* means that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications **should** be understood and the case carefully weighed before implementing any behavior described with this label.
**may**, or the adjective **optional**, means that an item is truly optional. One vendor may choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor may omit the same item. An implementation which does not include a particular option **must** be prepared to interoperate with another implementation which does include the option.

"Can" is used instead of "may" when referring to a possible circumstance or situation, as opposed to an optional facility.
"User" is used to refer to a human user, whereas "client" refers to the software being run by the user.
"Twitter " means the owner(s) of the service located at twitter.com for which this document describes the API
"twitter.com" means the server(s) against which the API works

Twitter Fan Club (fr)