Context Navigation

REST Web API

GET Data
POST Data

GET Data

GET/RATING URL

http://bilumi.org/Main/api/get/rating/<name>/ http://bilumi.org/Main/api/get/ratings/<name>/

<name>: Partial or complete name of real-world company or product.

Returns a JSON response that includes:

score : Aggregated, inherited rating averaged with default interest weightings
customized : Aggregated, inherited rating with customized user portfolio applied (same as score if not logged in)
count : Number of items contributing to rating
interest_ratings : List of rating, interest pairs
- interest
- rating

GET URLS

http://bilumi.org/Main/api/get/<entities>/

<entities>: Data type requested. Case-sensitive. Currently this includes:
- nodes
- node_types
- edges
- edge_types
- users
- reviews
- interests
- tags

eg,

http://bilumi.org/Main/api/get/rating/ http://bilumi.org/Main/api/get/ratings/ http://bilumi.org/Main/api/get/map/

REQUEST PARAMETERS (METHOD=GET)

All of the /Main/api/get URLs accept GET parameters:

id : id of entity to retrieve (response will still contain a list of entities; that list will either be a singleton or empty)
name : name of entities to retrieve. will first do an exact match on label. if nothing is found, will do a contains on label. if not too much is found (< 20 items), will do a contains on description.
slice : range of entities to return; eg,
- slice=:3 returns the 1st, 2nd and 3rd entities
- slice=1: returns all but the 1st entity
- slice=1:4 returns the 2nd, 3rd and 4th entities
- slice=2:3 returns the 3rd entity
tag : id or label of tag. Response will include only those entities that have that tag. Not applicable when id or name is used.
keys : keys representation for entities, eg keys=[['id']] would return just the id's field for each entity. See ENTITIES REPRESENTATION below for details.

The following parameters should only be used when <entities> equals nodes; note that none of these are applicable when id or name is used:

barcode : upc or ean code. Response will include only those nodes that have this barcode (barcodes can be re-used)
interest : id or label of interest. Response will include only those nodes that have a review in that interest
node_type : id or label of type. Response will include only nodes of this type

The following parameters should only be used when <entities> equals edges; note that none of these are applicable when id of name is used:

edge_type : id or label of type. Response will include only edges of this type

Note that all parameter values are AND'd together, thus ?interest=1&interest=2 will return only those nodes that have both behaviors in interest 1 and interest 2.

eg,

RESPONSE

The HTTP request returns a JSON response that includes:

<entities> : A list of object dictionaries that fulfill the request query.
count : Number of entities returned.

If <entities> equals nodes, the response also includes:

tags_used : The set of tags across all returned nodes
interests_used : The set of interests across all behaviors for all returned nodes (eg, AnimalRights?, CarbonFootprint?)
types_used : The set of types across all nodes (eg, Company, Product)

TODO: node representation should also include rating information

ENTITIES REPRESENTATION

The structures at the end of this section represent the JSON representation of data objects. That is, the dictionaries list the keys for which we want to retrieve data.

In addition to the single-word form, keys may also have the form returned_key=expression. expression is used on the object to retrieve a value, while returned_key is the key in the JSON response under which that value is listed.

The structure of the returned JSON is defined as follows:

No brackets, 'key', renders the value as a single string.
Single brackets, .., renders the value as a dictionary. The brackets may themselves contain structural keys. For example, ['user',['id','username']] might yield {"user": {"username": "bear", "id": 1}

Double brackets, [..], renders the value as a list. For example,

[['id','time','label','description', ['user',['id','username']]]]

, which is the structure for Behaviors (which although called Reviews in the top-level API, have not percolated any deeper), might yield

[
  {"user": {"username": "bear", "id": 1}, "description": "Reindeer Magic is polluting the North Pole", "label": "Reindeer Magic Harmful", "id": 1, "time": "2008-09-05 12:53:22"},
  {"user": {"username": "bear", "id": 1}, "description": "...", "label": "...", "id": 2, "time": "2008-09-05 12:53:22"},
  {"user": {"username": "bear", "id": 1}, "description": "...", "label": "...", "id": 3, "time": "2008-09-05 17:59:04"}
]

ENTITIES REPRESENTATION

    "Dimension": [['id','label','slug=slug.slug']],
    "NodeType":  [['id','label','description']],
    "EdgeType":  [['id','label','description']],
    
    "Tag": [['id','tag','count']],
    
    "Behavior": [['id','time','label','description',
                  ['dimension',['id','label','slug=slug.slug']],
                  ['user',['id','username']]]],
    
    "Argument": [['*','time',
                  ['user',['id','username']],
                  ['citations', [['*',
                                  ['article',['*',
                                              ['author',['*']],
                                              ['source',['*']],
                                              ]]]]]]],
    
    "User": [['id', 'username']],
    
    "Citation": [['id',
                  'passage',
                  ['argument',[]],
                  ['article',['id',
                              'title',
                              ['author',['id','name','description']],
                              ['source',['id','name','description']],
                              ]]]],
    
    "Node": [['id','label','description',
              ['parents=parent_edges', [['id=src_id', 'relationship=label']]],
              ['children=child_edges', [['id=dest.id', 'relationship=label']]],
              ['behaviors', [['id','label','description','dimension_id']]],
              ['types=typecasts', [['id=type.id','label=type.label']]],
              ['tags', [['tag']]],
              ]],
    
    "Edge": [['id','label','description']],

ERROR RESPONSE

error : A friendly and likely uninformative message about what went wrong
debug_type : Python Exception type
debug_args : List of Python Exception args, which will include at least the Exception's message

POST Data

URL

http://bilumi.org/Main/api/post/<entity>/

<entity>: Data type requested. Case-sensitive. Currently this includes:
- node
- edge
- rating
- review
TODO: add support for
- node_type_cast - links a node to a node_type
- edge_type_cast - links an edge to an edge_type_cast

eg,

http://bilumi.org/Main/api/post/node/

REQUEST BODY PARAMETERS (METHOD=POST)

entity = node POST parameters

label :
description :
type : id or label of existing node type
barcode : [optional]
tags : [optional] comma-separated list of existing or new tags

entity = edge POST parameters

label :
description :
parent : id or label of existing parent node
child : id or label of existing child node
type : [optional] id or label of existing node type
tags : [optional] comma-separated list of existing or new tags

entity = rating POST parameters

rating : 1-9 score
review : id of review (behavior) to rate

entity = review POST parameters

label
description
interest : id (not label)
node : id (not label)

All of the /Main/api/post URLs require a header with key 'Cookie' and value of a sessionid cookie. This cookie can be obtained from the response of logging in

http://bilumi.org/Main/api/login
POST parameters
- username
- password
You can register using our website (currently broken)
- http://bilumi.org/Main/account/register
RETURNED RESPONSE will contain the sessionid cookie under 'set-cookie'.
RETURNED CONTENT will contain a dictionary with key success on success, or error on failure.

The following python example demonstrates logging in and adding a node.

import urllib
import httplib2

http = httplib2.Http()
domain = "http://staging.thoughtandmemory.org"

def login(username='bear', password='bear'):
    """                                                                                             
    Login to BILUMI.org                                                                             
                                                                                                    
    """
    data = { 'username':username, 'password':password }
    body = urllib.urlencode(data)
    headers = {'Content-type': 'application/x-www-form-urlencoded'}
    response, content = http.request(
        "%s/Main/account/login/" % domain,
        method="POST",
        headers=headers,
        body=body)
    print "LOGIN\n  response: %s\n  content: %s" % (response, content)
    return response['set-cookie']

def add_node(cookie, label, description, ntype="Company", tags=""):
    """                                                                                             
    Add node                                                                                        
                                                                                                    
    """
    data = { 'label':label,
             'description':description,
             'type':ntype,
             'tags':tags
           }
    headers = { 'Content-type': 'application/x-www-form-urlencoded',
                'Cookie': cookie
              }
    response, content = http.request(
        "%s/Main/api/post/node/" % domain,
        method="POST",
        headers=headers,
        body=urllib.urlencode(data))
    print "ADD_NODE\n  response: %s\n  content: %s" % (response, content)

if __name__ == "__main__":
    cookie = login()
    add_node(cookie, "Water balloon", "Magical bear", tags="test")

RESPONSE

The HTTP request returns a JSON response that includes:

<entity> : An object dictionary containing the added entity.

ERROR RESPONSE

error : A friendly and likely informative message about what went wrong

Download in other formats:

Plain Text

Context Navigation

REST Web API

Table of Contents

GET Data

GET/RATING URL

GET URLS

REQUEST PARAMETERS (METHOD=GET)

RESPONSE

ENTITIES REPRESENTATION

ERROR RESPONSE

POST Data

URL

REQUEST BODY PARAMETERS (METHOD=POST)

RESPONSE

ERROR RESPONSE

Download in other formats: