Upcoming GMH API information

GMH API currently supports a RESTful interface. This means you can send an HTTP GET or POST to call exposed methods, and you'll get back an XML document in return.

When you send a request, you'll get a response in XML that looks like this:

<root>
  <code>1</code>
  <errors></errors>
  <active_key>readonly</active_key>
  <language>en</language>
  <pubdate>2009-07-25T23:14:15-06:00</pubdate>
  [Data in XML format - see individual method docs]
</root>

If there's an error, the response code field will be set to 0 and all relevant errors will be included in the XML content.

<root>
  <code>0</code>
  <errors>
    <error>[Error text provided]<error>
    <error>[Error text provided]<error>
  </errors>
<root>

Members authentication

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

POST http://api.givesmehope.com/account/login/<login>/<pass_md5>

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

Method: /view

Displays the GMH in several ways:

GET http://api.givesmehope.com.com/view/last/<page>

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

GET http://api.givesmehope.com.com/view/random

Displays a random GMH with it’s comments.

GET http://api.givesmehope.com.com/view/top/<page>

Displays the top GMHs. To specify an interval, change the parameter to: top_day / top_week / top_month

GET http://api.givesmehope.com.com/view/flop/<page>

Displays the flop GMHs. To specify an interval, change the parameter to: flop_day / flop_week / flop_month

GET http://api.givesmehope.com.com/view/cat/<cat>/<page>

Displays the latest GMHs in the selected category, by pages of 15 items.

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

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

POST http://api.givesmehope.com.com/view/search?search=<string>

Displays the GMHs corresponding to the search. To see the tips, have a look at the page concerning searches on GMH. Be careful, this is done in POST !

GET http://api.givesmehope.com.com/view/categories

Displays the categories available on the site.

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

Displays the members unread GMHs.

GET http://api.givesmehope.com.com/view/favorites

Displays the members favorite GMHs.

Method: /vote

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

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

Unique function of the vote action, replace with the number of the GMH being voted for, and maybe the type: yes / no

Method: /submit

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

GET http://api.givesmehope.com.com/submit

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

&author= // GMH author
&cat=gmh // Category
&text= // Text
&mail= // E-mail address (optional)

The category at the moment can be only 'gmh'. The same restrictions for the submission of a GMH via the site apply: notably the limitation of 300 characters.

Method: /comment

Send a comment on a GMH:

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

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

&id= // GMH ID
&text= // Text
&url= // Website (optional)

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

Method: /account

Utilities for the members accounts:

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

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

GET http://api.givesmehope.com.com/account/infos

Returns the information about the identified account.

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

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

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

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