Summary

You will find below the FML API documentation:

Getting started

API calls must be made through HTTP requests to the domain api.fmylife.com, like this:

GET/POST http://api.fmylife.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.fmylife.com.

Developer key

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.

Website language

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:

Members authentication

You can identify a member by FML account via the API, by sending their login and password (MD5 encrypted):

POST http://api.fmylife.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

Please note that inactive tokens will be deleted after 15 days of inactivity.

You are also strongly encouraged to send the IP address of your user with this parameter:

&ip=XXX.XXX.XXX.XXX

Error codes

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>

Badges

Users can win badges during their navigation or through their actions on the website. A badge tag can appear anytime in the main XML feed. It will look like this:

<badge>
<id>592</id>
<name>Le Gold Badge</name>
<type>gold</type>
<description>This badge was designed for you!</description>
</badge>

Don't forget to check for this tag at every request.

Method: /view

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.fmylife.com/view/last/<page>

Displays the latest FMLs displayed on the website by pages of 15 items.

GET http://api.fmylife.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.fmylife.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.fmylife.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.fmylife.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.fmylife.com/view/<number>[/nocomment]

Displays the FML #[number] with its associated comments. Add the /nocomment parameter to not display the comments.

GET http://api.fmylife.com/view/<number>?since_id=<id>

Displays the FML #[number] with its associated comments. The since_id parameter starts with 0, 15 comments by default. Set the since_id parameter with the last comment ID you received. You can set the nb parameter to change the number of comments per page.

GET http://api.fmylife.com/view/<number>/<page>

Displays the FML #[number] with its associated paginated comments. The page parameter starts with 1, 15 comments by default. You can set the nb parameter to change the number of comments per page.

POST http://api.fmylife.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.fmylife.com/view/categories

Displays the categories available on the site.

GET http://api.fmylife.com/view/new

Displays the member's unread FMLs.

GET http://api.fmylife.com/view/favorites[/page]

Displays the member's favorite FMLs.

GET http://api.fmylife.com/view/illustrated[/page]

Displays the illustrated FMLs. Variable page is set to 0 by default.

GET http://api.fmylife.com/view/illustrated/id/<id>

Displays the ID-specified illustrated FML.

Method: /thumb

Thumb up or down an FML comment. This function is for FML members only (token).

GET http://api.fmylife.com/thumb/<id>/<type>

Replace with the ID number of the FML comment you want to thumb, and the type: up / down

Method: /vote

This action allows voting for FMLs via the API. This function is for FML members only (token).

GET http://api.fmylife.com/vote/<number>/<type>

Unique function of the vote action, replace with the number of the FML being voted for, and the type: agree / deserved

Method: /submit

Sends a FML. This function is for FML members only (token).

GET http://api.fmylife.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)
&gender= // Gender (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.

If mail is set to true and a token is provided, the mail field is automatically filled with the user account's.

Method: /comment

Send a comment on an FML:

GET http://api.fmylife.com/comment

Be careful, the elements of the form are submitted in parameters:

&id= // FML ID
&text= // Text
&in_reply_to= // Global ID the comment replies to (optional)
&type= // Type commented (default: articles)

The user posting a comment must be a FML member, and identified as such via the API (token).

You can specify the type, by default it's articles (for commenting FMLs). For blog posts, set type=blog_posts.

Method: /edit

Edit a comment on an FML:

GET http://api.fmylife.com/edit

Be careful, the elements of the form are submitted in parameters:

&id= // Comment ID
&ref_id= // FML ID
&text= // Text
&type= // Type commented (default: articles)

The user editing a comment must be the author of the comment, and identified as such via the API (token).

Method: /mod

Integration of the auto-moderation system in the API:

GET http://api.fmylife.com/mod/last

Displays the last FML to be moderated.

GET http://api.fmylife.com/mod/list/<number>[/since_id]

Displays a list of a certain number of FML to be moderated. If you specify since_id, you'll get only the FML submitted after this ID.

GET http://api.fmylife.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.fmylife.com/mod/<yes|no>/<number>

Moderates whether YES or NO the FML in question should be accepted on the site.

Method: /abuse

Report an abuse through the API. User must be logged:

GET http://api.fmylife.com/abuse/article/<number>

Report an abuse about a currently auto-moderated FML.

GET http://api.fmylife.com/abuse/comment/<number>

Report an abuse about an FML comment. The number is the ID, not the public displayed number. You can add a "description" parameter.

Method: /account

Utilities for the members accounts:

GET http://api.fmylife.com/account/signup?mail=<mail>&login=<login>&pass=<pass>

Sign up for a new account. Either in POST or GET.

GET http://api.fmylife.com/account/infos?login=<login>

Returns informations about the specified account. If login is empty, returns informations about the identified account.

POST http://api.fmylife.com/account/update

Update profile informations. You can specify which information you want to update:

Note : For the title parameter, the value changes according to the website's locales. For the timezone parameter, please use standard values.

POST http://api.fmylife.com/account/upload?photo=<photo>

Uploads a profile picture for the identified account. Must be a multipart POST request.

GET http://api.fmylife.com/account/upload/delete

Deletes the profile picture for the identified account.

GET http://api.fmylife.com/account/favorites/[add|delete]/<id>

Add/delete a specified FML to/from the user's favorites.

GET http://api.fmylife.com/account/follow/[do|undo]/<id>

Follow/Unfollow specified FML comments.

GET http://api.fmylife.com/account/option/<name>/[0|1]

Set / Unset authenticated user option. Available option names : display.people (FR only).

GET http://api.fmylife.com/account/badges

Displays identified user's badges.

GET http://api.fmylife.com/account/statuses

Displays identified user's submitted stories statuses.

GET http://api.fmylife.com/account/mailbox/summary[/page]

Displays the received messages from the user. You can use the "summary" parameter to hide the text tag. Pages of 30 items by default, but you can add a &nbpp= numeric parameter.

POST http://api.fmylife.com/account/mailbox/compose

Compose a message to another member, using following parameters:

GET http://api.fmylife.com/account/mailbox/view/<id>?page=<page>

Displays the specified message discussion by pages of 100 messages. Add the read=false parameter if you don't want to marke the discussion as read.

GET http://api.fmylife.com/account/mailbox/read/<id>

Marks as read the specified message discussion.

GET http://api.fmylife.com/account/mailbox/delete/<id>

Delete the specified message ID discussion. User can be the sender or the receiver.

GET http://api.fmylife.com/account/contacts/list

Displays the user's contacts list.

GET http://api.fmylife.com/account/contacts/add/<loginid>

Adds a user to user's contacts list.

GET http://api.fmylife.com/account/contacts/delete/<loginid>

Deletes a user from user's contacts list.

GET http://api.fmylife.com/account/contacts/block/<loginid>

Block the specified login ID from user's contacts list.

GET http://api.fmylife.com/account/contacts/unblock/<loginid>

Un-block a user from user's contacts list.

GET http://api.fmylife.com/account/logout/[token]

Deletes the API’s basic token to completely disconnect the member.

POST http://api.fmylife.com/account/password?mail=<mail>

Send a mail to the user in order to reset his lost password. Submitted mail must match the account mail.

POST http://api.fmylife.com/account/validation

Send one more time the account validation mail to the authenticated user.

POST http://api.fmylife.com/account/delete

Send a mail with a link to delete the authenticated user's account.

Method: /blog

GET http://api.fmylife.com/blog/summary[/page]

Displays the latest blog posts summaries published on the website by pages of 15 items.

GET http://api.fmylife.com/blog/view/<number>[/nocomment]

Displays the blog post #[number] with its associated comments. Add the /nocomment parameter to hide the comments.

Method: /dev

GET http://api.fmylife.com/dev

Displays several statistics about your API developpers account.