An User friendly API design concept

Originally posted by Liju on Google Groups.

Hi Friends,

We have been using many type of APIs to accomplish our task. For me API is kind of a toolkit provided to build our own tool out of it. By saying that we may use one or more API for a single task.
There are situations where I won’t be able to get some function which I am looking for from the toolkit, may be it exists but it is difficult. This made me think about how to create an user friendly API.
At least we can standardize some part of it, for eg: read and write.
So let me show you what I am trying to say.

>>> api.person.data()

If somebody look at this method and might say, Am I suppose to get any data from here or have to set anything, If you have good documentation for this API , your problem got solved,
but for someone who wanna try different API for the same time he may not have good time to read all the docs, and try things out, rather he will quickly try out from the terminal itself by experimenting
with the known methods. If the API is not a straight forward one then we have to quit trying it or look for some assistance.

So, what if we have a method classifications in our API for quick finding of methods and attributes, for eg: like getters and setters, likewise we can implement an API with method classifications(in my word).

from database import db

class MyAPI(object):
    def __init__(self):
        self.person = Person()

class Person(object):
    def __init__(self):
        self.db = db()
        self.db.register_user(username="liju.kunnummal")
        self.read = PersonRead(self.db)
        self.write = PersonWrite(self.db)

class PersonRead(object):
    def __init__(self, db):
        self.db = db

    def all_shows(self):
        return self.db.get_user_shows()

    def user_data(self):
        return self.db.get_user_data()

class PersonWrite(object):
    def __init__(self, db):
        self.db = db

    def current_show(self, show_name):
        self.db.set_user_current_show(show_name)

    def current_task(self, current_task):
        self.db.set_current_task(current_task)

Now, how do we use this?

>>> api = MyAPI()
>>> api.person.read.allShows()
>>> api.person.read.user_data()
>>> api.person.write.current_show("SHOW02")
>>> api.person.write.current_task(taskObj)

When we type api.person.____ we will think about what we wanna do, do we have to read something or set something, if we wanna read anything then api.person.read.____ for setting something then api.person.write.____ do for you.

this will reduce the ambiguity while using methods.

So, obviously you will have doubt that what if other than read/write, sure we can add that too,
take this example,

If you wanna execute something, still we can use the same idea by classifying methods,

class Person(object):
    def __init__(self):
        self.db = db()
        self.db.register_user(username="liju.kunnummal")
        self.read = PersonRead(self.db)
        self.write = PersonWrite(self.db)
        self.process = PersonProcess(self.db)

and we can add all execution methods to PersonProcess class
later we can use,

>>> api.person.process.used_data()
>>> api.person.process.all_task()

This applicable to all instance we have in our API, which avoids confusion among methods while using them and gives you an user friendly API.