Skip to content

Thinks to be remembered while developing an API

August 5, 2009
It is often hard to decide whether a program is good or bad – if it crashes without doing anything useful, it is bad. If the program cannot compile, it is even worse. But if it runs, helps to get a work done, just sometimes crashes, it is hardly good, but also it does not need to completely bad. The decision depends on the perception/awareness of the evaluator. And the same applies when one tries to judge a design. It does not matter whether it is a UI design or API design. Again the personal perception is important.
On the other hand software engineering is done by engineers and important part of engineering is its measurability. So the ultimate goal for reasoning about design is to make it measurable, to suppress the subjective opinions and define set of requirements that will be used to measure the quality of the design.
As shown on the example of a good/bad program, the user¬タルs subjective feeling is important. And it is important in design as well. But in case of API, which stands for the interface between the internals of an application and a programmatic usage of its functionality, the person who will have the subjective feeling is the programmer using the API. He is the API user. He is the one who will judge the design and represent opinions whether it is good or bad. Of course, such opinions will be absolutely personal, based on personal experience gain during learning the design and using the API. The easier is for the API users to make their job done, the better perception of the design they will get.
The external programmer is more concerned by the time needed to learn the API, by the amount of code needed to get his tasks done and by the stability of the contract.
¬タワThe art of making good API lays exactly in meeting these opposite requirements. ¬タワ
As usually one shall optimize for larger audience, for bigger effect. Usually the amount of people using an API is a way larger than those coding it and that is why one shall take a special care to simplify the life of these users. Little uneasiness in implementing the application is acceptable, if the life of majority of users is simpler. To better address user needs, it is necessary to know and understand their requirements.
¬タワIf an API allows easy implementation of the common tasks, it is a good API. ¬タワ
That is why the “initial step in API design is to investigate and collect the scenarios for possible uses of the application.” Having these use cases written down allows evaluation of each aspect of the API and validation of the design. The use cases serve as a fixed point to which one validates the design of API. It is practically impossible to judge the quality of a design, but it is relatively easy to check whether the design satisfies required use cases or not.
Once a use case becomes supported, it should stay supported until the end of the world .
No comments yet

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: