Perfect API design
Good API design specifications
Why is good application programming interface (API) design so difficult? Just throw together a few classes with a few basic methods on them and call it done.
You cocould do this, if you don't mind other developers cursing you-and referencing your API as an anti-pattern. How can this be avoided? Aim for perfection with API design. Yes, perfection.
Why is it always difficult to design well-designed application interfaces (APIS)? interfaces are not just defining classes and methods, but can be used. In this way, only the designer knows how to use the interface, and the nonstandard interface will be complained by other programmers, or will be introduced as an inverse example. So how can we avoid these problems and design good APIs?
Designing an API is similar to designing a user interface. both are entry points into an application and the first thing a user (or developer) Interacts. picture your favorite consumer electronics device in conjunction with its competitors. mine is my beloved TiVo digital video recorder. what makes the TiVo UI great?
The Design of application interfaces (APIS) is similar to the design of the UI, through which users interact with the application. Let's talk about your favorite electronic products and their competitors. TiVo is my favorite digital video recorder. TiVo has a very good interface design:
- Usage is simple
- Misuse is difficult
- TiVo does one thing well
- It does not do anything unexpected
- It has never crashed in multiple years of Usage
- Actions/tasks are intuitive and easy to discover
- The UI is consistent, polished and perfect, or close to it
- Easy to use
- Easy to understand and use
- Important Functions
- Not expecting to do everything well
- In years of use, the system will not crash.
- Features are intuitive and easy to find
- Unified UI design
The same principles hold true with API design. let's pick on one of my favorite API anti-patterns from the com world: iolecommandtarget: exec. this API is typically used to enable some kind of object, and the container that it sits in, to dispatch commands to each other.
HRESULT Exec (
const GUID *pguidCmdGroup, // Pointer to command group
DWORD nCmdID, // Identifier of command to execute
DWORD nCmdExecOpt, // Options for executing the command
VARIANTARG *pvaIn, // Pointer to input arguments
VARIANTARG *pvaOut // Pointer to command output
);
This principle also applies to the design of application interfaces (APIS. Let's take a look at an example from com: iolecommandtarget: exec. This API is usually used to execute a command.
An example implementation is a COM control that communicates with its container to modify menu items and toolbars. this API is a slightly stronger-typed version of a command interface that takes in a generic string dictating what the implementation is supposed to do.
A common example is how to modify the menu or toolbar through its container in the COM control. This API uses a string to determine the command, but does not pass strong type discrimination.
Let's analyze this API according to the principles just discussed.
Finally, we will analyze this API based on the above principles.
Is the API intuitive and discoverable?Is this the first place a developer wocould look to modify a toolbar? Likely it's not, unless you have the tribal knowledge about this API. Even a search of msdn documentation wocould end in frustration.
Is this API very intuitive and easy to discover? When a programmer wants to modify the toolbar, will he first see this place? If not, unless there is a tribal knowledge base for this API, it will fail even if you can search through msdn.
Is it simple?The API takes five parameters that are generically named. documentation is required to thoroughly understand the usage of each parameter. A Simple API exhibits intention and clarity just by the name of the object (for context) and the name of the method.
Simple? This API requires the input of five parameters. The author of this document needs to be very clear about the usage of each parameter. A Simple API can describe its main functions through its context object and its name. A good API should be self-described.
Is the API stronugly typed and difficult to misuse?No. The variants are not stronugly typed and the execution options are not enumerations, but generic Dwords. stronugly typed parameters help find errors at compile time instead of at run time.
Is this API strongly typed? Is it easy to pass wrong parameters? Obviously not. variants is not strongly typed, and execution parameters are not defined as enumeration types but integers. A strongly typed parameter will help you discover errors during compilation rather than runtime.
Is the API cohesive?An implementation of this function typically has responsibilities, not just one. A well-named API for one specific purpose (e.g ., addtoolbarbutton) is much more cohesive. an Implementation of the exec method likely switches on the command ID and has different actions based on this condition.
Is this API cohesive? Obviously, this API has multiple responsibilities, not a single responsibility. APIS with a single responsibility are often more independent, and naming is easier to read, for example, addtoolbarbutton.
Is the API free of side effects?Hard to say, but an implementation of the API cocould do practically anything due to its lack of cohesion.
Does this API have no side effects? It is hard to say no. Due to the lack of cohesion, this API can actually do something else.
Is it reliable?The famous design principle "design to interfaces" helps enforce testability on an object. this API is inherently testable, but the number of test cases to verify may be huge due to its lack of cohesion. reliability is at risk.
Is this API reliable? A well-known principle of interface design is that it requires testability. Obviously, this interface is measurable, but the number of test cases is huge, and stability is a risk point.
Is it consistent?This API does have some consistency in that it returns an hresult and uses guids to identify sets of information. however, it is difficult to judge consistency without knowing how poorly designed the rest of the interfaces on an object are.
Is this API consistent with other system APIs? Like other APIs, the returned value is hresult and guid is used to specify information. However, if you do not know much about other interfaces of this object, it is difficult to make a judgment.
Anyone learning to use iolecommandtarget: exec likely needs instruction about its usage from a peer or a book. the best APIs are simple and usable without documentation, although documentation may still be required to understand details such as error handling.
When using this interface, anyone may need to learn how to use it from their peers or books. Good APIs should be simple and can be used correctly without documentation. Of course, if you want to know more about interface error handling, the document will help you.
In conclusion, your APIs and the APIS you review shocould be as easy to use as TiVo.
A highly discoverable, strongly typed, cohesive, side-effect free, reliable, consistent, and polished API makes your developers 'lives easier by increasing satisfaction and decreasing support costs. using Interfaces in the Microsoft. net Framework are great examples. to achieve all of these design gains, aim for perfection when designing or reviewing any API design.
In general, the API you designed or the API you reviewed should be as easy to use as TiVo. Highly self-descriptive, strongly typed, cohesive, reliable without any side effects, consistent APIs will make your users more happy and their satisfaction will increase, the cost of support is reduced. Many interfaces of Microsoft. NET Framework are good examples. Use the above principles to improve your API when designing or reviewing APIs in your daily work.
