Grebe API

Grebe is the name of a blogging app. This is Grebe's API description. It's currently used at http://maketoledo.com.

It uses REST and JSON.

Each function below is preceded with /api/v1 in the URI, so for Make Toledo, it would be http://maketoledo.com/api/v1.

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

At the moment, I don't have SSL enabled for MakeToledo.com, and OAuth is not used.

Users

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

• 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]

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

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

• Logout user JR.
  GET request.
  /users/JR/logout

• 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" }

• Update password for existing account. User must be logged-in.
  PUT request.
  /users/password
  Client sends JSON to the API:
  { "old_password" : "oldpwdtext", "new_password" : "newpwdtxt", "verify_password" : "newpwdtxt", "user_name" : "userA", "user_id" : 123 }
  Client code also packages up the login data for user_name, user_id, and session_id into the PUT request.
  To-Do: remove the redundant information.

• Update e-mail and/or profile description for the user.
  PUT request.
  /users
  Client sends JSON to the API:
  { "user_name" : "userA", "user_id" : 123, "desc_markup" : "my profile page info for others to view.", "email" : "usera@usera.com" }
  Client code also packages up the login data for user_name, user_id, and session_id into the PUT request.
  To-Do: remove the redundant information.

Posts

• Show stream of posts.
  GET request.
  /posts
/posts/?type=note&author=jr
/posts/?type=draft&author=jr
/posts/?sortby=modified
/posts/?page=3
/posts/?author=jr
  To-Do: support
  /posts/?year=2014&month=05&day=02

• Retrieve single post.
  GET request.
  /posts/5
/posts/5?/text=markup
/posts/5/?text=html
/posts/5/?text=full
  To-Do: support
  /posts/5/?fields=title,uri_title,created_date,etc.

• Retrieve list of related posts.
  GET request.
  /posts/5/?related=yes

• 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 5
  /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

• Search for the phrase "text string"
  /searches/string/text+string

• Retrieve page three of the search results for the phrase "text string"
  /searches/string/text+string/3

• Retrieve posts that contain mentions of both "Toledo" AND "Detroit"
  /searches/string/toledo+AND+detroit

• Retrieve posts that contain either mentions of "pizza" OR "bread"
  /searches/string/pizza+OR+bread

• Retrieve posts with the tag "food"
  /searches/tag/food

• Retrieve page three of the search results for tag "food"
  /searches/tag/food/3

• Retrieve posts that contain the tags "beer" AND "cheese"
  /searches/tag/beer+AND+cheese

• Retrieve posts that contain either the tags "fishing" OR "cycling"
  /searches/tag/fishing+OR+cycling

Returned JSON

Get post for user who is not the author.

{
"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|",
}