You will find below the FML API documentation:
API calls must be made through HTTP requests to the domain api.betacie.com, like this:
GET/POST http://api.betacie.com/view/last
The return format is XML, which in its simplest shape looks like this:
<root>
( ... answer ... )
<code>1</code>
<errors/>
</root>
XML returns will not be explained, do tests by yourself, they are explicit enough not to be documented. :)
In order to make tests without affecting the real database, you can use sandbox.betacie.com as server name instead of the usual api.betacie.com.
In order to fully use the API, you need a developer key. You have to request it on the website (API section), you'll instantly receive a key in your e-mail box.
Once you got your key, you'll have to always mention it as a parameter in your API calls:
?key=XXXXXXXXXXXXX
This key allows us to create some statistics about API use, and therefore improve it in a faster and simpler way. We will also be able to contact you to notify you about major API updates.
As you probably already know, a french version of FML exists ([url=http://www.viedemerde.fr]www.viedemerde.fr[/url]). The API supports both languages, and will display the english version by default even if you do not specify the language in the following parameter:
?language=en
Other languages available:
You can identify a member by FML account via the API, by sending their login and password (MD5 encrypted):
POST http://api.betacie.com/account/login/<login>/<md5_password>
By calling up this method (in POST), you will receive a character chain called token, that you will need to act upon their account via the API:
&token=XXXXXXXXXXXXX
You are also strongly encouraged to send the IP address of your user with this parameter:
&ip=XXX.XXX.XXX.XXX
The error codes returned by the API consist of 4 numeric characters: XYYY, where X is the type of the error, and YYY the error code itself.
<errors>
<error code="XYYY">Error text</error>
</errors>
Displays the FML in several ways.
If the token is specified, you will have extra data added to the displayed FML:
Available actions below:
GET http://api.betacie.com/view/last/<page>
Displays the latest FMLs displayed on the website by pages of 15 items.
GET http://api.betacie.com/view/random[/number|nosex]
Displays [number] random FML with it’s comments (default is 1). If you set the /nosex parameter, random won't display intimacy stories.
GET http://api.betacie.com/view/top/<page>
Displays the top FMLs. To specify an interval, change the parameter to: top_day / top_week / top_month
GET http://api.betacie.com/view/flop/<page>
Displays the flop FMLs. To specify an interval, change the parameter to: flop_day / flop_week / flop_month
GET http://api.betacie.com/view/<cat>/<page>
Displays the latest FMLs in the selected category, by pages of 15 items. The parameter can be: love / money / kids / work / health / sex / miscellaneous
GET http://api.betacie.com/view/<number>[/nocomment]
Displays the FML #[number] with its associated comments. Add the /nocomment parameter to not display the comments.
POST http://api.betacie.com/view/search?search=<string>
Displays the FMLs corresponding to the search. To see the tips, have a look at the page concerning searches on FML. Be careful, this is done in POST!
GET http://api.betacie.com/view/categories
Displays the categories available on the site.
GET http://api.betacie.com/view/new
Displays the member's unread FMLs.
GET http://api.betacie.com/view/favorites
Displays the member's favorite FMLs.
GET http://api.betacie.com/view/illustrated[/page]
Displays the illustrated FMLs. Variable page is set to 0 by default.
This action allows voting for FMLs via the API. This function is for FML members only (token).
GET http://api.betacie.com/vote/<number>/<type>
Unique function of the vote action, replace with the number of the FML being voted for, and maybe the type: agree / deserved
Sends a FML. This function is for FML members only (token).
GET http://api.betacie.com/submit
Be careful, the elements of the form are submitted in parameters:
&author= // FML author &cat= // Category &text= // Text &mail= // E-mail address (optional)
The category can be: love/money/work/health/sex/miscellaneous. The same restrictions for the submission of a FML via the site apply: notably the limitation of 300 characters.
Send a comment on a FML:
GET http://api.betacie.com/comment
Be careful, the elements of the form are submitted in parameters:
&id= // FML ID &text= // Text &url= // Website (optional)
The user posting a comment must be a FML member, and identified as such via the API (token).
Integration of the auto-moderation system in the API:
GET http://api.betacie.com/mod/last
Displays the last FML to be moderated.
GET http://api.betacie.com/mod/view[/number]
Without the [number], this command returns the list of all the FMLs left to be moderated. With the [number], it displays the particular FML.
GET http://api.betacie.com/mod/<yes|no>/<number>
Moderates whether YES or NO the FML in question should be accepted on the site.
Report an abuse through the API. User must be logged:
GET http://api.betacie.com/abuse/article/<number>
Report an abuse about a currently auto-moderated FML.
GET http://api.betacie.com/abuse/comment/<number>
Report an abuse about an FML comment. The number is the ID, not the public displayed number.
Utilities for the members accounts:
GET http://api.betacie.com/account/signup?mail=<mail>&login=<login>&pass=<pass>
Sign up for a new account. Either in POST or GET.
GET http://api.betacie.com/account/infos
Returns the information about the identified account.
GET http://api.betacie.com/account/favorites/[add|delete]/<id>
Add/delete a specified FML to/from the user's favorites.
GET http://api.betacie.com/account/follow/[do|undo]/<id>
Follow/Unfollow specified FML comments.
GET http://api.betacie.com/account/logout/[token]
Deletes the API’s basic token to completely disconnect the member.
GET http://api.betacie.com/dev
Displays several statistics about your API developpers account.