Grebe API

markdown=yes

Grebe blogging API description. It's currently being used at <http://maketoledo.soupmode.com>.

It uses REST and JSON.

Each function below is preceded with ``/api/v1`` in the URI. So for Soupmode, it would be ``http://soupmode.com/api/v1``.

Example of activating a new user account:  
``http://soupmode.com/api/v1/users/activate/ru8wkn0ol2ql3bm9``

At the moment, I don't have SSL enabled at Soupmode.com, and OAuth is not used. Strengthening authentication is on the to-do list.


### Users

Except for activating a user account, URIs for GETs and PUTs end with the query string:  
``/?user_name=[user_name]&amp;user_id=[user_id]&amp;session_id=[session_id]``

* Retrieve profile page info for user name JR.  
GET request.  
``/users/JR``

* Create a new user account.  
POST request.  
``/users``  
Client sends JSON to the API:  
``{ "user_name" : "userA", "email"     : "usera@usera.com" }``

* Activate user account.  
GET request.  
``/users/activate/[user_digest]``

* Logout user JR.  
GET request.  
``/users/JR/logout``

* Login user.  
Post request.  
``/users/login``  
Client sends JSON to the API:  
``{ "email"     : "usera@usera.com", "password" : "plaintextpwd" }``

* Retrieve new password for existing account. User would not be logged in. This would be executed for someone who forgot or lost a password.  
POST request.  
``/users/password``  
Client sends JSON to the API:  
``{ "user_name" : "userA", "email"     : "usera@usera.com" }``

* Change password for existing account. User must be logged-in.  
PUT request.  
``/users/password``

* Update e-mail and/or profile description for the user.  
PUT request.  
``/users``


### Articles

For GET requests, each URI ends with the query string:  
``/?user_name=[user_name]&amp;user_id=[user_id]&amp;session_id=[session_id]``

The POST requests will also need the above name=value pairs encoded and sent to the API.

Example displaying article number 5:  
GET request.  
``http://soupmode.com/api/v1/messages/5/?user_name=JR&amp;user_id=23&amp;session_id=ru8er03jjg3k40vjl09``

* Show all messages created by or sent to the logged-in user. This message stream is displayed on the site's homepage.  
GET request.  
``/messages``

* Show page three of the stream.  
GET request.  
``/messages/page/3``

* Retrieve message ID number 5.  
GET request.  
``/messages/5``

* Create a new message.  
POST request.   
``/messages``  
In addition to the name=value logged-in credentials listed above, the client sends the following JSON to the API:  
``{ "message_text" : "this is the message text." }``

* Retrieve all reply messages for message ID number 5.  
GET request.  
``/messages/5/replies``