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

Example of retrieving the posts that get displayed on the homepage at maketoledo.com:
http://maketoledo.com/api/v1/posts

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

For GETs that require the user to be logged-in, the URI ends with the query string:
/?user_name=[user_name]&user_id=[user_id]&session_id=[session_id]

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

Users

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

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

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

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

Created a new user account.

{"email":"testuser1403714996@test.com","password":"hx7epyyd","user_digest":"Afvh7gO1t9a8ptJSqVzITg","status":201,"user_id":"4","description":"Created","user_name":"testuser1403714996"}

Logged-in.


{"session_id":"rvBvLDXmPjohnbiTM9t2MQ","status":200,"user_id":"4","description":"OK","user_name":"testuser1403714996"}

Updated password.


{"session_id":"BSif8wk2iqSks6QNXIySw","status":200,"user_id":"4","user_name":"testuser1403714996"}

Created an article, note, or draft post.


{"status":200,"post_id":"119","description":"Created"}

Updated an article, note, or draft post.


{"status":201,"post_id":"121","description":"Updated"}

Version list for a post.


{"author_name":"testuser1403714996","formatted_modified_date":"Jun 25, 2014","status":200,"version":"2","version_list":[{"version_date":"Jun 25, 2014","author_name":"testuser1403714996","version_time":"11:49:58 AM","version":"1","post_id":"122","uri_title":"20140625-16-49-58-this-will-be-the-post-title","edit_reason":null}],"description":"OK","post_id":"121","formatted_modified_time":"11:49:59 AM","title":"new UPDATED post text 2014-06-25 16:49:59","uri_title":"new-updated-post-text-20140625-16-49-59","edit_reason":null}

Version compare info.


{"top_version":{"author_id":"4","author_name":"testuser1403714996","markup_text":"# new UPDATED post text 2014-06-25 16:49:59\n\nhere is some more text.\n\ntags #grebe #blogging","formatted_text":"<p>here is some more text.</p>\n\n<p>tags <a href=\"/tag/grebe\">#grebe</a> <a href=\"/tag/blogging\">#blogging</a></p>\n\n","parent_id":"0","formatted_modified_time":"11:49:59 AM","post_id":"121","post_type":"article","edit_reason":null,"formatted_modified_date":"Jun 25, 2014","modified_date":"2014-06-25 16:49:59","version":"2","created_date":"2014-06-25 16:49:58","tags":"|grebe|blogging|","post_status":"o","post_digest":"gLeraLqPjeuJXIgFEicPkg","formatted_created_time":"11:49:58 AM","title":"new UPDATED post text 2014-06-25 16:49:59","formatted_created_date":"Jun 25, 2014","uri_title":"new-updated-post-text-20140625-16-49-59"},"status":200,"version_data":{"right_uri_title":"new-updated-post-text-20140625-16-49-59","right_time":"11:49:59 am","right_title":"new UPDATED post text 2014-06-25 16:49:59","left_version":"1","right_post_id":"121","right_version":"2","right_date":"Jun 25, 2014","left_parent_id":"121","left_post_id":"122","right_parent_id":"0","left_uri_title":"20140625-16-49-58-this-will-be-the-post-title","left_time":"11:49:58 am","left_title":"2014-06-25 16:49:58 this will be the post title","left_date":"Jun 25, 2014"},"description":"OK","compare_results":[{"left":"# 2014-06-25 16:49:58 this will be the post title","rightdiffclass":"changed","modindicator":"c","leftdiffclass":"changed","right":"# new UPDATED post text 2014-06-25 16:49:59"},{"left":"&nbsp;","rightdiffclass":"unmodified","modindicator":"u","leftdiffclass":"unmodified","right":"&nbsp;"},{"left":"here is the start of the body text","rightdiffclass":"unmodified","modindicator":"-","leftdiffclass":"removed","right":"&nbsp;"},{"left":"&nbsp;","rightdiffclass":"unmodified","modindicator":"-","leftdiffclass":"removed","right":"&nbsp;"},{"left":"here is some more text.","rightdiffclass":"unmodified","modindicator":"u","leftdiffclass":"unmodified","right":"here is some more text."},{"left":"&nbsp;","rightdiffclass":"unmodified","modindicator":"u","leftdiffclass":"unmodified","right":"&nbsp;"},{"left":"testin **markdown bolding**","rightdiffclass":"changed","modindicator":"c","leftdiffclass":"changed","right":"tags #grebe #blogging"},{"left":"&nbsp;","rightdiffclass":"unmodified","modindicator":"-","leftdiffclass":"removed","right":"&nbsp;"},{"left":"hashtag #test #perl","rightdiffclass":"unmodified","modindicator":"-","leftdiffclass":"removed","right":"&nbsp;"}]}

Deleted or Undeleted a post.


{"status":200,"description":"OK"}

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

Stream of posts.

Tag list by sorted by count


{"total_unique_tags":20,"sort_by":"count","tag_list":[{"tag_count":"10","tag_name":"test"},{"tag_count":"10","tag_name":"perl"},{"tag_count":"9","tag_name":"home"},{"tag_count":"8","tag_name":"beer"},{"tag_count":"7","tag_name":"beverage"},{"tag_count":"5","tag_name":"recipe"},{"tag_count":"3","tag_name":"food"},{"tag_count":"2","tag_name":"todo"},{"tag_count":"2","tag_name":"flower"},{"tag_count":"2","tag_name":"garden"},{"tag_count":"2","tag_name":"nature"},{"tag_count":"2","tag_name":"toledo"},{"tag_count":"1","tag_name":"insect"},{"tag_count":"1","tag_name":"environment"},{"tag_count":"1","tag_name":"tag2"},{"tag_count":"1","tag_name":"blogging"},{"tag_count":"1","tag_name":"business"},{"tag_count":"1","tag_name":"bread"},{"tag_count":"1","tag_name":"tag1"},{"tag_count":"1","tag_name":"grebe"}],"status":200,"description":"OK"}

Tag list sorted by name.


{"total_unique_tags":20,"sort_by":"name","tag_list":[{"tag_count":"8","tag_name":"beer"},{"tag_count":"7","tag_name":"beverage"},{"tag_count":"1","tag_name":"blogging"},{"tag_count":"1","tag_name":"bread"},{"tag_count":"1","tag_name":"business"},{"tag_count":"1","tag_name":"environment"},{"tag_count":"2","tag_name":"flower"},{"tag_count":"3","tag_name":"food"},{"tag_count":"2","tag_name":"garden"},{"tag_count":"1","tag_name":"grebe"},{"tag_count":"9","tag_name":"home"},{"tag_count":"1","tag_name":"insect"},{"tag_count":"2","tag_name":"nature"},{"tag_count":"10","tag_name":"perl"},{"tag_count":"5","tag_name":"recipe"},{"tag_count":"1","tag_name":"tag1"},{"tag_count":"1","tag_name":"tag2"},{"tag_count":"10","tag_name":"test"},{"tag_count":"2","tag_name":"todo"},{"tag_count":"2","tag_name":"toledo"}],"status":200,"description":"OK"}

From JR's : articles
807 words - 10983 chars - 4 min read
created on Apr 24, 2014 at 12:41:57 pm
updated on Jul 18, 2014 at 06:13:25 pm - #
source - versions

Related articles
Grebe API Returned JSON - Aug 19, 2014
Grebe API - Old Page - Jul 18, 2014
Grebe code changes to apply at other installs - Apr 17, 2015
Grebe Feature List - Aug 19, 2014
Creating new blog tool based upon Junco and Kinglet - Jun 18, 2014
more >>