The Design Rules of API

=========================
The Design Rules of API
=========================

:Author: gashero
:Date: 2012-02-24

Good API is usable for caller, but bad API is hard to debug. This article will introduce some design rule of API in my opinion. Every one of the rules is base on some failure's lesson.

1. Separate ID-LIST and GET-ONE

Your API need one of ID-LIST or GET-ONE. The ID-LIST API will return a list of object_id, but no detail information about the object. The GET-ONE API will return only ONE object's full information (written by gashero).

If your API designed by this rule, most requirement will be cover by these two type of API. Someone get list, someone get detail. ID-LIST API will return in limit time.

If NOT? If you develop API for every requirement, you will get many API, and many repeat code. API will be not reuseful. And if a requirement need a new object's attribution, you must modify the API. But if you use ID-LIST & GET-ONE, you just only need modify the Application's code, GET-ONE API has enough attribution.

2. Dataset slice, count & offset

Every ID-LIST API need dataset slice, by count & offset. If your requirement do not mention it now, it will be appear later. So, if you have designed it, you do not need modify it later.

Notice some language allow parameter have default value, you can give a default value 0 to offset, but DO NOT give default value to count. Because caller maybe ignore it, and then cause some bug. For example, caller maybe want to get all object id list, but he forget the count parameter, the default count will lost some id.

3. Start with action

API's naming is a difficult task, because you need a meanful name, but avoid same to other API's name. Name a API start with a action is good choice. Like Hungarian notation, name lead with it's class, not data type.

Some useful prefix of API's name:

1. add: create an new object.
2. delete: delete an object.
3. update: modify an object's 1 field value.
4. get: get 1 object's full detail by object_id.
5. list: get list of object's id match some rule.
6. count: get count of object match some rule.

4. Do not call eachother

API would not call eachother, avoid depend on eachother. Independent or reuse, most time, independent is more useful. Sometimes, you may think something is reusable, but actually it not.

5. Set operate

If a API focus update set of objects. Right way is just add/delete the element in the set, not write whole set. Because, write whole set need large communication bandwidth, and this method can not get right result in concurrent environment.

6. No super API

If you provide a API have many feature, caller will abuse it everywhere. When you want to do some reconstruction, these API will kill you. Because you do not know caller how to use it.

Super API break the API, make API not clear, make caller inject the internel of your implemention.

7. More debug information, not "return NULL"

Debug is more important than performance. "return NULL" is not a good idea for debug, because it transfer nothing to caller.

You need define a exceptioin class, with some field to tell caller what is wrong. Some useful field:

1. errnum: error number, can be recognize by program.
2. errmsg: error message, can be read by people.

8. Update API, (id, field, value)

Modify some object's field just need these three parameters. Select an object by object_id, modify its field to value. Field can be select by a string, this parttern can match many requirement.

9. More string as type, no magic number

There is many type field in interface or database design. A string can be readable, it's more friendly to debug. But if a magic number as type field in a large system, caller will crash.

10. Separate interface and logic

Interface is sometimes very simple without logic, too simple to test. But if logic in interface, it's hard to test.

Automatic test is very good for your software quality. So separate interface and logic will make logic suit for test. Unittest will help you increase quality.

11. Do not mix code

Mix code will decrease your program's readability. If you write SQL in your function, code will become confusion.

You can write SQL on top of your source file, and refer in your code.