Grebe API

<https://github.com/WhiteHouse/api-standards>

<http://micheltriana.com/2013/09/27/http-status-codes-in-rest-web-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`


### Posts

When Deleting and un-deleting posts 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 post number 5:  
GET request.  
`http://soupmode.com/api/v1/posts/5/?user_name=JR&amp;user_id=23&amp;session_id=ru8er03jjg3k40vjl09`

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

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

* Show all posts for user JR.  
GET request.  
`/posts/user/JR`

* Show page three of the stream of posts for user JR.  
GET request.  
`/posts/user/JR/page/3`

* Retrieve post for ID number 5.  
GET request.  
`/posts/5`  
If logged-in user is author, then additional information is returned, such as markup_text, post_digest, etc., which is good for editing the post.

* Retrieve post for URI title this-is-a-test.  
GET request.  
`/posts/this-is-a-test`  
If logged-in user is author, then additional information is returned, such as markup_text, post_digest, etc., which is good for editing the post.

* Create a new post.  
POST request.   
`/posts`  
In addition to the name=value logged-in credentials listed above, the client sends the following JSON to the API:  
`{ "post_text" : "this is the post text." }`  
Sample returned JSON:  
`{"post_id":"9","status":201,"description":"Created"}`

* Update post with ID number 5.   
PUT request  
`/posts`  
In addition to the name=value logged-in credentials listed above, the client sends the following JSON to the API:  
`{ "post_id": "5", "post_digest": "ru48f9re39jf023jf", "post_text":"updated text"}`

* Delete an post with ID number 5.  
GET request.  
`/posts/delete/5`  

* Undelete an post with ID number 5.  
GET request.  
`/posts/undelete/5`  


## Articles

* Show all articles for user JR.  
GET request.  
`/articles/user/JR`

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



## Notes

* Show all notes for user JR.  
GET request.  
`/notes/user/JR`

* Show page three of the stream of notes for user JR.  
GET request.  
`/notes/user/JR/page/3`


## Drafts

* Show all drafts for user JR.  
GET request.  
`/drafts/user/JR`

* Show page three of the stream of drafts for user JR.  
GET request.  
`/drafts/user/JR/page/3`



## Tags

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

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


## Versions

* Show version list for post ID or post URL/URI title  
GET request  
`/versions/5`  
`/versions/this-is-a-test`

* Compare two post versions based upon their numeric post IDs. This example compares post post ID 1 and post ID 2  
GET request  
`/versions/1/2`


## Searches

GET requests

`/searches/string/text+string`
`/searches/string/text+string/3` - page 3 of stream

prob like `/searches/string/text%2Bstring`

`/searches/tag/tagname`  
`/searches/tag/tagname/3`  - page 3 of stream


## Returned JSON

### Get post for user who is not the author.

code.
{
"status"                   :  200,
"description"              :  "OK",
"parent_id"                :  "0",
"post_id"               :  "9",
"title"                    :  "2014-05-02 15:13:57 this will be the title",
"uri_title"                :  "20140502-15-13-57-this-will-be-the-title",
"formatted_text"           :  "<p>here is the start of the body text</p>\n\n<p>here is some more text.</p>\n\n<p>testin <strong>markdown bolding</strong></p>\n\n<p>hashtag <a href=\"/tag/test\">#test</a> <a href=\"/tag/perl\">#perl</a></p>\n",
"author_name"              :  "testuser1398830044",
"created_date"             :  "2014-05-02 15:13:58",
"modified_date"            :  "2014-05-02 15:13:58",
"formatted_created_date"   :  "May 02, 2014"
"formatted_modified_date"  :  "May 02, 2014",
"reader_is_author"         :  0,
"post_status"           :  "o",
"post_type"             :  "a",
"related_posts_count"   :  2,
"version"                  :  "1",
"tags"                     :  "|test|perl|",
}
code..

br.

---

---

## May 5, 2014 Proposed Changes

### posts

Show all posts. 
GET request. 
/posts  
/posts/?type=note   
/posts/?type=draft   
/posts/?sortby=modified  
/posts/?page=3  
/posts/?author=jr  
/posts/?year=2014&amp;month=05&amp;day=02

Retrieve post for ID number 5. 
GET request. 
/posts/5 
/posts/5?/text=markup  
/posts/5/?text=html  
/posts/5/?fields=title,uri_title,created_date, etc.

Retrieve list of related posts.  
/posts/5/?related=yes

Create a new post. 
POST request. 
/posts 
In addition to the name=value logged-in credentials listed above, the client sends the following JSON to the API:  
`{ "post_text" : "this is the post text." }`   
Sample returned JSON: 
`{"post_id":"9","status":201,"description":"Created"}`

Update post with ID number 5. 
PUT request 
/posts 
In addition to the name=value logged-in credentials listed above, the client sends the following JSON to the API:  
`{ "post_id": "5", "post_digest": "ru48f9re39jf023jf", "post_text":"updated text"}`

Delete an post with ID number 5.  
/posts/5/?action=delete

Undelete an post with ID number 5.  
/posts/5/?action=undelete



### Versions

Show version list for post ID or post URL/URI title  
/versions/5


Compare two post versions based upon their numeric post IDs. This example compares post post ID 1 and post ID 2  
/versions/1/2


### Tags

Show list of tags, sorted by name   
/tags/?sortby=name

Show list of tags, sorted by count  
/tags/?sortby=count

Show stream of posts for tag food.  
/tags/food  
OR /searches/tag/tagname 



### Searches

/searches/text+string  
/searches/string/text+string  
/searches/string/text+string/?page=3   
/searches/tag/tagname  
/searches/tag/tagname/?page=3



 #grebe - #blogging - #api - #programming