• Users
• Articles
• Tags
• Versions

Grebe API

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

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]&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 article number 5:
GET request.
http://soupmode.com/api/v1/articles/5/?user_name=JR&user_id=23&session_id=ru8er03jjg3k40vjl09

• Show all articles.
  GET request.
  /articles

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

• 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

• 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., which is good for editing the article.

• 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., which is good for editing the article.

• Retrieves only the markup text for ID number 5, which is good for viewing the source markup for the article.
  GET request.
  /articles/markup/5

• Retrieves only the HTML text for ID number 5, which is good for displaying an article.
  GET request.
  /articles/html/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

Versions

• Show version list for article ID or article URL/URI title
  GET request
  /versions/5
/versions/this-is-a-test

• Compare two article versions based upon their numeric article IDs. This example compares article article ID 1 and article ID 2
  GET request
  /versions/1/2

  #grebe - #blogging - #api - #programming