System wide calls

/bmarks

Usage

GET /api/v1/bmarks

Return a list of the most recent bookmarks

query param:api_key optional - the api key for your account to make the call with
query param:count - the number in the result you wish to return
query param:page - the page number to get results for based off of the count specified
query param:with_content - do you wish the readable content of the urls if available
query param:callback - wrap JSON response in an optional callback

Status Codes

success 200:If successful a “200 OK” will be returned, with json body of message: done
error 403:if the api key is not valid or missing then this is an unauthorized request

Example

requests.get('http://127.0.0.1:6543/api/v1/bmarks?count=2&api_key=12345...')
>>>{
    "count": 2,
    "bmarks": [
        {
            "username": "admin",
            "updated": "2011-07-29 22:23:42",
            "extended": "",
            "description": "Bookie: Recent Bookmarks",
            "tags": [
                {
                    "tid": 3,
                    "name": "test"
                },
                {
                    "tid": 2,
                    "name": "bookmarks"
                }
            ],
            "bid": 2,
            "stored": "2011-06-21 13:20:26",
            "inserted_by": null,
            "tag_str": "test bookmarks",
            "clicks": 1,
            "hash_id": "c605a21cf19560"
        },
        {
            "username": "admin",
            "updated": "2011-07-15 14:25:16",
            "extended": "Bookie Documentation Home",
            "description": "Bookie Website",
            "tags": [
                {
                    "tid": 2,
                    "name": "bookmarks"
                }
            ],
            "bid": 1,
            "stored": "2011-06-20 11:42:47",
            "inserted_by": null,
            "tag_str": "bookmarks",
            "clicks": 1,
            "hash_id": "c5c21717c99797"
        }
    ],
    "tag_filter": null,
    "page": 0,
    "max_count": 10
}

/bmarks/search/:terms

Usage

GET /api/v1/bmarks/search/:terms

Return a list of the user’s bookmarks based on the fulltext search of the given terms. There can be one or more search terms. All search terms are OR‘d together. Fulltext search will find matches in the description, extended, and tag_string fields of a bookmark. You can also perform fulltext search against the readable content of pages with the correct query parameter from below.

query param:api_key optional - the api key for your account to make the call with
query param:count - the number in the result you wish to return
query param:page - the page number to get results for based off of the count specified
query param:search_content - include the readable text in the fulltext search. This can slow down the response.
query param:with_content - do you wish the readable content of the urls if available
query param:callback - wrap JSON response in an optional callback

Status Codes

success 200:If successful a “200 OK” will be returned, with json body of message: done
error 403:if the api key is not valid or missing then this is an unauthorized request

Example

requests.get('http://127.0.0.1:6543/api/v1/bmarks/search/ubuntu?api_key=12345...')
>>>> {
         "page": null,
         "phrase": "ubuntu",
         "result_count": 2,
         "search_results": [
           {
             "bid": 3,
             "clicks": 0,
             "description": "nickelanddime.png (PNG Image, 1200x1400 pixels) - Scaled (64%)",
             "extended": "This is the extended description",
             "hash_id": "adb017923e1f56",
             "inserted_by": "importer",
             "stored": "2011-02-25 15:13:00",
             "tag_str": "nickelanddime kerfuffle banshee amazon ubuntu ubuntu-one canonical",
             "tags": [
               {
                 "name": "ubuntu",
                 "tid": 4
               },
               {
                 "name": "canonical",
                 "tid": 10
               }
             ],
             "total_clicks": 0,
             "updated": "",
             "url": "http://www.ndftz.com/nickelanddime.png",
             "username": "admin"
           },
           {
             "bid": 77,
             "clicks": 0,
             "description": "My title: ubuntu forum archive about echolinux",
             "extended": "",
             "hash_id": "3e9a37d4f7cd74",
             "inserted_by": "importer",
             "stored": "2010-07-08 19:30:18",
             "tag_str": "ham linux",
             "tags": [
               {
                 "name": "ham",
                 "tid": 89
               },
               {
                 "name": "linux",
                 "tid": 103
               }
             ],
             "total_clicks": 0,
             "updated": "",
             "url": "http://ubuntuforums.org/archive/index.php/t-973929.html",
             "username": "admin"
           }
         ],
         "username": "admin",
         "with_content": false
     }

/suspend

Usage

POST /api/v1/suspend

Creates a reset of the account. The user account is locked, an email is fired to the user’s email address on file, and an activation code is contained within that is required to unlock the account.

query param:api_key required - the api key for your account to make the call with
query param:email required - the email address of the user we’re wanting to reset
query param:callback - wrap JSON response in an optional callback

Status Codes

success 200:If successful a “200 OK” will be returned, with json body of message: done
error 404:Could not find a user for this email address to suspend the account
error 406:No email address submitted in the request so we can’t suspend anyone

Example

requests.post('http://127.0.0.1:6543/api/v1/suspend?api_key=12345...&email=testing@dummy.com')
>>> {
    "message":  """Your account has been marked for reactivation. Please check your email for instructions to reset your password""",
}

requests.post('http://127.0.0.1:6543/api/v1/suspend?api_key=12345...')
>>> {
    "error":  "Please submit an email address",
}

requests.post('http://127.0.0.1:6543/api/v1/suspend?api_key=12345...&email=testing@dummy.com')
>>> {
    "error":  "You've already marked your account for reactivation.  Please check your email for the reactivation link. Make sure to check your spam folder.",
    "username": admin
}

Usage

DELETE /api/v1/suspend

Reactive the account. Basically we’re “deleting the suspend” on the account. This requires the reactivation key that was sent to the user in the activation email.

query param:username - string username of the user we’re activating
query param:activation - string activation code returned emailed from the POST call
query param:password - a new password to reactivate this account to
query param:callback - wrap JSON response in an optional callback

Status Codes

success 200:If successful a “200 OK” will be returned, with json body of message: done
error 406:The password supplied doesn’t satisfy complexity requirements.
error 500:There was some issue restoring the account. Send for help

Example

requests.delete('http://127.0.0.1:6543/api/v1/suspend?api_key=12345&activation=behehe&password=admin')
>>> {
    "message": "Account activated, please log in",
    "username": "admin"
}

requests.delete('http://127.0.0.1:6543/api/v1/suspend?api_key=12345&activation=behehe&password=12')
>>> {
    "error": "Come on, pick a real password please"
}

/:username/invite

Usage

POST /api/v1/admin/invite

Allows a user to create an invitation to another user in the system.

query param:api_key required - the api key for your account to make the call with
query param:email required - the email address of the new user to invite
query param:callback - wrap JSON response in an optional callback

Status Codes

success 200:If successful a “200 OK” will be returned, with json body of message: done
error 406:No email address submitted in the request so we can’t invite anyone

Example

requests.post('http://127.0.0.1:6543/api/v1/admin/invite?api_key=12345...&email=testing@dummy.com')
>>> {
    "message":  """done""",
}

requests.post('http://127.0.0.1:6543/api/v1/admin/invite?api_key=12345...')
>>> {
    "error":  "Please submit an email address",
}

requests.post('http://127.0.0.1:6543/api/v1/admin/invite?api_key=12345...&email=testing@dummy.com')
>>> {
    "error":  "This user has already been invited to the system.",
    "email": "testing@dummy.com"
}

/stats/bookmarks

Usage

GET /api/v1/stats/bookmarks

Returns basic statistics about number of bookmarks in the database

Status Codes

success 200:If successful a “200 OK” will be returned, with json body of count, and unique_count

Example

requests.get('http://127.0.0.1:6543/api/v1/stats/bookmarks')
>>> {
    "count": 115047,
    "unique_count": 108060
}

/stats/users

Usage

GET /api/v1/stats/users

Returns basic statistics about number of users in the database

Status Codes

success 200:If successful a “200 OK” will be returned, with json body of count, activations, and with_bookmarks

Example

requests.get('http://127.0.0.1:6543/api/v1/stats/users')
>>> {
    "count": 875,
    "activations": 133,
    "with_bookmarks": 388
}