![Page 1: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/1.jpg)
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 1/35
The Craft of API Design
Clifford WolfROCK Linux - http://www.rocklinux.org/
Csync2 - http://oss.linbit.com/csync2/
STFL - http://www.clifford.at/stfl/
SPL - http://www.clifford.at/spl/
![Page 2: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/2.jpg)
Introduction
● What are APIs? (1/2)
● What are APIs? (2/2)
● Why are APIs so important?● Why is API-Design so
important?
APIs Everywhere
Some Guidelines
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 2/35
Introduction
![Page 3: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/3.jpg)
Introduction
● What are APIs? (1/2)
● What are APIs? (2/2)
● Why are APIs so important?● Why is API-Design so
important?
APIs Everywhere
Some Guidelines
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 3/35
What are APIs? (1/2)
■ APIs are the (programatical) face of any piece ofprogramming work.
■ This is not limited to libraries intended for a broad use.
■ It also covers the internal APIs found in every non-trivialprogram.
![Page 4: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/4.jpg)
Introduction
● What are APIs? (1/2)
● What are APIs? (2/2)
● Why are APIs so important?● Why is API-Design so
important?
APIs Everywhere
Some Guidelines
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 4/35
What are APIs? (2/2)
■ APIs can be seen as extensions to the functionality of aprogramming language.
■ A programming language comes with a very limited built-invocabulary (set of functions and keywords).
■ Every program module extends this vocabulary using its API.
![Page 5: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/5.jpg)
Introduction
● What are APIs? (1/2)
● What are APIs? (2/2)
● Why are APIs so important?● Why is API-Design so
important?
APIs Everywhere
Some Guidelines
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 5/35
Why are APIs so important?
■ Today’s programming projects tend to become huge prettyfast.
■ It is hard to fully understand a huge program.■ So projects are broken up into modules with the APIs
connecting them.
■ With this seperation, it enables the programmer to focus onone module without the need of knowing the rest of theproject inside out.
■ This can’t work out unless the APIs are stable and cleanlyseperating the modules from each other.
![Page 6: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/6.jpg)
Introduction
● What are APIs? (1/2)
● What are APIs? (2/2)
● Why are APIs so important?● Why is API-Design so
important?
APIs Everywhere
Some Guidelines
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 6/35
Why is API-Design so important?
■ Projects tend to “grow” with the APIs happening instead ofbeeing designed.
■ A well designed API enables the programmer to change amodule’s internals without the need for changing the API orother modules.
■ So if the API is good, everything else can also be improvedlater in the process.
■ But changing an API is always complicated, especially if theAPI has grown already a big user base.
![Page 7: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/7.jpg)
Introduction
APIs Everywhere
● Frameworks
● Standard APIs (1/2)
● Standard APIs (2/2)
● Toolchain Libraries
● Program Modules
Some Guidelines
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 7/35
APIs Everywhere
![Page 8: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/8.jpg)
Introduction
APIs Everywhere
● Frameworks
● Standard APIs (1/2)
● Standard APIs (2/2)
● Toolchain Libraries
● Program Modules
Some Guidelines
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 8/35
Frameworks
■ Frameworks are getting more important than theprogramming languages they are written for and in.
■ Example given:◆ Ruby on Rails
![Page 9: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/9.jpg)
Introduction
APIs Everywhere
● Frameworks
● Standard APIs (1/2)
● Standard APIs (2/2)
● Toolchain Libraries
● Program Modules
Some Guidelines
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 9/35
Standard APIs (1/2)
■ Some APIs are part of standards and independend ofimplementations.
■ Example given:◆ Standard C Library◆ The POSIX system call layer◆ The Verilog PLI layer◆ The MPI API
■ A thing to ponder:Usually it takes a few hours to learn a new language,learning the standard libraries API is the hard part.
![Page 10: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/10.jpg)
Introduction
APIs Everywhere
● Frameworks
● Standard APIs (1/2)
● Standard APIs (2/2)
● Toolchain Libraries
● Program Modules
Some Guidelines
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 10/35
Standard APIs (2/2)
■ Some APIs are even independend of programminglanguages.
■ Example given:◆ The DOM API
■ Changing a standard API once it is published and in use isclose to impossible.
![Page 11: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/11.jpg)
Introduction
APIs Everywhere
● Frameworks
● Standard APIs (1/2)
● Standard APIs (2/2)
● Toolchain Libraries
● Program Modules
Some Guidelines
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 11/35
Toolchain Libraries
■ Most of today’s applications don’t implement a singlenon-trivial algorithm.
■ Instead ready-to-use libraries are used.
■ Example given:◆ APIs to sort functions vs. sorting algorithms -
Which one is more important for the daily work of anapplication programmer?
![Page 12: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/12.jpg)
Introduction
APIs Everywhere
● Frameworks
● Standard APIs (1/2)
● Standard APIs (2/2)
● Toolchain Libraries
● Program Modules
Some Guidelines
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 12/35
Program Modules
■ Today’s software projects are usually split up in smallmodules.
■ This is pimarily done to fight complexity.
■ The whole effort is useless if the APIs between this modulesaren’t well designed.
![Page 13: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/13.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 13/35
Some Guidelines
![Page 14: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/14.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 14/35
Introduction (1/2)
■ I will present some Guidelines for API design.
■ None of them is an absolute rule.
■ But I believe they bring up some questions everyonedesigning an API should worry about.
■ Feedback is always welcome.
![Page 15: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/15.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 15/35
Introduction (2/2)
■ The following rules and things to ponder might be useful:◆ For designing new APIs◆ For cleaning up existing APIs◆ For judging others APIs
■ Every minute cut in API design will hit you hard later.
![Page 16: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/16.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 16/35
Hard to use wrong (1/2)
■ An API must be hard to use wrong.
■ This is different from easy to use right.
![Page 17: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/17.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 17/35
Hard to use wrong (2/2)
Good example:
char * get_current_dir_name(void);
Returns a malloced string containing the absolute pathname ofthe current working directory. (GNU extension)
Bad example:
char * strncpy(char * dest, const char * src, size_t n);
If there is no null byte among the first n bytes of src, the resultwill not be null-terminated.
![Page 18: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/18.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 18/35
Be self-descriptive (1/2)
■ The name should indicate what it does.
■ Use names for function parameters when the languageprovides them.
■ The API should pass the "Telephone test".
Good example:
egrep --recursive --exclude-dir .svn Copyright .
Bad example:
char * exclude_dir_vect[] = { ".svn", NULL };fictional_egrep_function(0, 0, 1, 0, 0, NULL, NULL,
exclude_dir_vect, NULL, NULL, "Copyright", ".");
![Page 19: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/19.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 19/35
Be self-descriptive (2/2)
Good example:
if (strstr(haystack, "needle"))printf("Found a needle!\n");
Bad example:
print "Found a needle!\n" if haystack =˜ /needle/;
Good example:
int on_exit(void ( * function)(int , void * ), void * arg);
Bad example:
sighandler_t signal(int signum, sighandler_t handler);
![Page 20: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/20.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 20/35
Hide something
■ An API must hide something.
■ The inner workings of a module must not dictate the API.
Good and bad example:
void qsort(void * base, size_t nmemb, size_t size,int( * compar)(const void * , const void * ));
![Page 21: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/21.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 21/35
Don’t overoptimize
■ Allow for changes in the algorithm.■ This is where optimization happens!
Common failure: Trading a ’fast API’ for less flexibility.
Bad Example:
void qsort(void * base, size_t nmemb, size_t size,int( * compar)(const void * , const void * ));
(A user context pointer should be passed thru to compare.)
![Page 22: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/22.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 22/35
Support User Contexts
■ Always pass a void user context pointer to callback functions.■ Global variables should never be used for this!
■ Always configure a library using some kind of context object.■ Global variables should never be used for this!
■ Bad examples: qsort(), LibXML2■ Good examples: epool, PCRE
![Page 23: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/23.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 23/35
Be Pragmatic
■ Each module/function should do one thing well.
Bad examples:■ Using select() as nanosleep/usleep replacement. (4.2BSD)
Good examples:■ BSD socket API■ Most POSIX System Calls
![Page 24: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/24.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 24/35
Be Consistent
■ Stick to a metaphor for API names.
■ Stick to a lexical naming scheme.
■ Don’t mix plural and singular in names.
■ Always use the same name for the same thing.
■ Avoid off-by-one confusions.
![Page 25: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/25.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 25/35
Be Restrictive
■ Make a clear distinction between internal and external APIs.
■ Use accessor functions to access data structures.
■ Don’t export struct internals when the user should only passthe pointer.
■ Everything that does not affect the API can be changedeasily!
![Page 26: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/26.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 26/35
Be Selective
■ Limit the API to an easy to overview set of functions, ifpossible.
■ Good example: PCRE API
■ Provide an easy-to-use API for the most common use case,if feasible.
■ Good example: CURL API
![Page 27: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/27.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 27/35
Free everything
■ Provide done() , destroy() or cleanup() functions.
■ Make sure that it is possible to free every resource allocatedby your library.
■ Use memory debuggers like valgrind to verify yourimplementation.
Bad example:The QT library
![Page 28: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/28.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 28/35
Two-level-documentation
■ Provide at least two levels of documentation:◆ The big picture / tutorial◆ Function, Class, etc. reference
■ Tools like doxygen can only help with the latter one.
■ Always assume that the reader of your documentation startswith zero knowlegde of your API.
■ Always start with describing the bigger context.
![Page 29: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/29.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 29/35
Document the data layout
■ Data structures etc. are almost ever under-documented.
■ But often understanding the data structures is the keyelement for understanding an API.
■ In good programs the data structure tends to dictate theimperative part of the program, not the other way around.
Bad example:man pages
![Page 30: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/30.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 30/35
Stick to a freeing-paradigm
■ Always be clear who is supposed to free what resource.
■ Make a decision for one paradigm and stick to it.
■ Freeing resources is the boring part.
■ Nevertheless it’s one of the most critical aspects in APIdesign.
(Know your contracts!)
![Page 31: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/31.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 31/35
Program defensively
■ Be liberal with what you acceppt.
■ Be conservative with what you pass to the outside world.
■ Check for the impossible case.
■ Fail early when you have to fail.
■ Leave all checks in the production code.
![Page 32: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/32.jpg)
Introduction
APIs Everywhere
Some Guidelines
● Introduction (1/2)
● Introduction (2/2)
● Hard to use wrong (1/2)
● Hard to use wrong (2/2)
● Be self-descriptive (1/2)
● Be self-descriptive (2/2)
● Hide something
● Don’t overoptimize
● Support User Contexts
● Be Pragmatic
● Be Consistent
● Be Restrictive
● Be Selective
● Free everything
● Two-level-documentation
● Document the data layout
● Stick to a freeing-paradigm
● Program defensively
● Support many languages
References
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 32/35
Support many languages
■ Support as many programming languages as possible.
■ Use the swig library to export a C/C++ API to the scriptingworld.
■ Provide command line tools to make the API’s functionalityaccessible from an ordinary UNIX shell.
■ Provide a thin C-wrapper for C++ libraries.
■ Use MinGW or Cygwin to create a Win32 port of your library.
![Page 33: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/33.jpg)
Introduction
APIs Everywhere
Some Guidelines
References
● Books
● This Presentation
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 33/35
References
![Page 34: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/34.jpg)
Introduction
APIs Everywhere
Some Guidelines
References
● Books
● This Presentation
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 34/35
Books
■ The Pragmatic ProgrammerHunt and Thomas (ISBN-13: 978-0-201-61622-4)
■ The Mythical Man-MonthBrooks (ISBN-13: 978-0-201-83595-3)
■ The Elements of Programming StyleKerninghan and Plauger (ISBN: 0-07-034207-5)
![Page 35: Clifford Wolf · Today’s programming projects tend to become huge pretty fast. It is hard to fully understand a huge program. So projects are broken up into modules with the APIs](https://reader033.vdocuments.mx/reader033/viewer/2022053023/6053d09e09f9f06f772b3d6e/html5/thumbnails/35.jpg)
Introduction
APIs Everywhere
Some Guidelines
References
● Books
● This Presentation
Clifford Wolf, September 21, 2008 http://www.clifford.at/ - p. 35/35
This Presentation
■ Clifford Wolfhttp://www.clifford.at/
■ More Presentationshttp://www.clifford.at/papers/
■ This Presentationhttp://www.clifford.at/papers/2008/apidesign/