3 min

Grebe API

tags: #grebe - #api - #rest - #json

This is Grebe's API description. It's currently used at http://maketoledo.com and http://birdbrainsbrewing.com with a test site at http://grebe.soupmode.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

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

From JR's : articles
563 words - 4384 chars - 3 min read
created on
updated on - #
source - versions - backlinks

Related articles
Grebe API Returned JSON - Aug 19, 2014
Short list of REST API info - Jan 13, 2017
Kinglet User and Programmer Documentation - Mar 19, 2014
Junco REST JSON simple GET for a post - Sep 20, 2013
API-first-development design - Jun 23, 2014
more >>



A     A     A     A     A

© 2013-2017 JotHut - Online notebook

current date: Dec 3, 2024 - 4:13 p.m. EST