Grebe API - Old Page

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

Use three simple, common response codes indicating (1) success, (2) failure due to client-side problem, (3) failure due to server-side problem:

200 - OK 400 - Bad Request 500 - Internal Server Error

Grebe blog 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]

• 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

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

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. - will implement later

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

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]&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.

Example displaying post number 5:
GET request.
http://maketoledo.com/api/v1/posts/5/?user_name=JR&user_id=23&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.

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

May 5, 2014 Proposed Changes

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

Test Scripts Names

Listed in the order that they are executed:

[x] a_create-user.t [x] b_activate-account.t [x] c_login.t d_create-draft.t d_create-note.t d_create-post.t e_read-post.t ff_update-post.t f_read-post-notloggedin.t g_read-tag-list-by-count.t g_read-tag-list-by-name.t hh_read-post-markup-notloggedin.t h_read-stream.t i_read-stream-notloggedin.t [x] t_update-profile.t [x] u_read-user.t vv_delete-post.t vvv_undelete-post.t w_read-version-list.t ww_compare-versions.t [x] z_update-password.t [x] zz_logout.t [x] zzz_create-new-password.t

#grebe - #blogging - #api - #programming