API Design Best Practices by Alibaba Researcher Gu Pu


API Design Rule: What Is a Good API?

Best practices

A Good API Example: Posix File API

int open(const char *path, int oflag, .../*,mode_t mode */); 
int close (int filedes);
int remove( const char *fname );
ssize_t write(int fildes, const void *buf, size_t nbyte);
ssize_t read(int fildes, void *buf, size_t nbyte);
int open(const char *path, int oflag, .../*,mode_t mode */);

Document Well

Carefully Define the “Resource” of Your API

Choose the Right Level of Abstraction

Prefer Using Different Models for Different Layers

Naming and Identification of the Resource

disk: string,
path: string
account: number
routing: number

What Are the Conceptually Reasonable Operations for This Resource?

For Update Operations, Prefer Idempotence Whenever Feasible


Batch Mutations

Be Aware of the Full Replacement Risks

UpdateFoo(Foo newFoo);
UpdateFoo {
Foo newFoo;
boolen update_field1; // update mask
boolen update_field2; // update mask

Don’t Create Your Own Error Codes or Error Mechanisms





Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store