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

When Deleting and un-deleting articles by the logged-in author, the URI for GET requests ends with the query string:  
`/?user_name=[user_name]&amp;user_id=[user_id]&amp;session_id=[session_id]`

POST and PUT 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/articles/5/?user_name=JR&amp;user_id=23&amp;session_id=ru8er03jjg3k40vjl09`

* Show all articles.  
GET request.  
`/articles`

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

* Retrieve article for ID number 5.  
GET request.  
`/articles/5`  
If logged-in user is author, then additional information is returned, such as markup_text, article_digest, etc.

* Retrieve article for URI title this-is-a-test.  
GET request.  
`/articles/this-is-a-test`  
If logged-in user is author, then additional information is returned, such as markup_text, article_digest, etc.

* Retrieves only the markup text for ID number 5  
GET request.
`/articles/markup/5`

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

* Update article with ID number 5.   
PUT request  
`/articles`  
In addition to the name=value logged-in credentials listed above, the client sends the following JSON to the API:  
`{ "article_id": "5", "article_digest": "ru48f9re39jf023jf", "article_text":"updated text"}`

* Delete an article with ID number 5.  
GET request.  
`/articles/delete/5`  

* Undelete an article with ID number 5.  
GET request.  
`/articles/undelete/5`  


## Tags

* Show list of tags, sorted by name  
GET request  
`/tags/name`

* Show list of tags, sorted by count  
GET request  
`/tags/count`




 #grebe - #blogging - #api - #programming