How to design a good API

So far, the API has been responsible for nearly two years, the two years to find the existing API has more and more problems, but many APIs once released can no longer be modified, instant upgrade and maintenance is necessary. Once the API changes, it can have a huge cost to the relevant caller, and the user needs to troubleshoot all the calling code and need to adjust all the relevant parts, which are extra for them. If you have worked hard to complete these, you have found related bugs, which will hit the user even more. If the API changes frequently, users lose confidence in the provider and thus affect their current business.

But why do we have to modify the API? Looking more beautiful for the API? To provide more functionality? To provide better performance? Or does it just feel like it's time to change? For users, they prefer to use a stable but seemingly less fashionable API, which does not mean that we no longer improve the API. When the maintenance costs of the bad API are getting bigger, I think that's when we're going to refactor it.

If I could go back and do it again, what would be the best API in my mind?

Judging whether an API is good or not is not simply based on the first version, it depends on whether the API can still exist over time and whether it remains well. The API interface of the cake is various, but the good API interface for the user must satisfy the following several points:

• Easy to learn: There are perfect documentation and provide as many examples and Copy-paste code as other design work, you should apply the least surprising principle.
• Easy to use: No complicated procedures, complicated details, easy to learn; Flexible APIs allow sorting by fields, customizable paging, sorting and filtering, and more. A complete API means that the desired functionality is included.
• Difficult to misuse: For detailed error hints, some experienced users can use the API directly without needing to read the document.

And for developers, the requirements are different:

• Easy to read: Code is written only once, but you need to read the code when debugging or modifying it.
• Easy to develop: a minimized interface is the use of as few classes as possible with as few class members. This makes it easier to understand, memorize, debug, and change the API.

How to do the above points, the following are some summary:

1. For use case design

If an API is widely used, it is not possible to understand all users who use the API. If designers want to be able to design a widely used API, then they must stand in the user's perspective to understand how to design the API library, and how to design such an API library.

2. Adopt a good design idea

In the design process, if you can design according to the following way, will make this API life longer

• Design for use cases, collect user suggestions, simulate users, ensure the API design is easy to use and reasonable
• Ensure that subsequent requirements can be completed in the form of an extension
• The first edition does as little as possible, as new requirements can be done in the form of extensions, so doing less is an effective solution to suppress API design errors
• Provide clear API and documentation specifications to avoid user misuse of API, especially avoid API (see section I) Post-level API being known and misused by users

In addition, some specific design methods are listed below:

• Method is better than property
• Factory method is superior to constructor function
• Avoid excessive inheritance
• Avoid affecting APIs due to optimization or reuse of code
• Interface-Oriented Programming
• Extension parameters should be convenient
• Proper positioning of components to determine how many interfaces are exposed
• Provide extension points

3. Avoid extremes of opinion

When designing the API, be sure to avoid any extreme opinions, especially the following points:

• Must be pretty (API doesn't need to be pretty)
• The API must be used correctly (it is difficult for users to understand how to properly use Api,api's designers to fully consider the misuse of the API: If an API could be misused, it would be misused)
• Must be simple (we are always faced with complex requirements, the API that can be both balanced is a better API)
• Must be high performance (performance can be optimized by other means and should not affect API design)
• Must be absolutely compatible (although this article has always mentioned how to ensure compatibility, but we still have to be aware that some very few cases will encounter incompatibilities is tolerable)

4. Effective API Review

After the API design is completed, a thorough design review is required and the focus of the review is as follows:

• Use case-driven, before the review must provide a sound usage cases, to ensure the rationality and completeness of use cases.
• Consistency is consistent with the interface style of other modules in the system, and is consistent with the design of the symmetric interface.
• Simple and straightforward, the API should be easy to understand, easy to learn and use the API is not easy to misuse, bring us more trouble.
• API as little as possible, if an API can be exposed or can not be exposed, then do not expose him, until the user really needs to make it a public interface is not too late.
• Support continuous improvement, whether the API can be easily expanded to add functionality and optimization.

5. Improve the testability of the API

The API needs to be testable, the test should not rely on implementation, testing the full API, especially after the rigorous "Compatibility integration testing" API, more assurance that the upgrade process does not appear compatibility issues. The compatibility integration test refers to a set of test cases that use the API at the user's stand. After the API upgrade, detect whether this set of test cases will fully meet the expected pass test and identify compatibility issues as much as possible.

6. Ensure backward compatibility of the API

For every designer of the API, there is a desire to be "backwards compatible" because both the current API user and the potential API user Trust only those compatible APIs. But backwards compatibility has multiple levels of meaning, and backwards compatibility at different levels also means different importance and complexity.

7. Maintain progressive improvement

In the past we have always wanted to be able to completely overturn the existing "unreasonable" design, and then follow the current "good" thinking, redesign the API, but after a period of time, will encounter the same situation, need to overturn again. If we do not have an effective gradual improvement approach, relying on overturning existing designs, redesign the API only allows us to return to the starting point and then reproduce the previous process. An effective and continuous improvement approach is needed to improve the API to make it better while the API is compatible.

8. Grasp the life cycle of the API

Each API has a life cycle, and we need to make the API's life cycle longer and let it fade out smoothly at the end of the API's life cycle.

• Tell users how we design, avoid misuse, provide guidance, and use errors often as a killer to shorten API life
• Provide a trial period, the API can not initially be stable, the trial API to have a stronger vitality
• For API Rating: Internal use, secondary development use, development or trial, stability, deprecated API. While avoiding misuse of APIs, we can increase the impact of the API by adjusting the level of the APIs, and we can end the lifecycle of an API more gracefully.

The process of developing an API is actually a process of communicating and communicating. The two sides of communication are API users and API designers.

9. A number of specific implementation programmes

When an API inevitably dies or changes, we should accept and face the fact that there are several ways to adjust the API under the premise of ensuring compatibility:

• Mark the API as deprecated and re-establish a new API. If an API inevitably dies, it's the only way.
• Add additional parameters or parameter options to add functionality
• Splitting the existing API into two parts provides a streamlined core API that was implemented by encapsulating the core API. This is typically used to resolve a user's need for a code-lite version.
• Encapsulation on the basis of existing APIs, providing a richer package or class

Some good API examples: the Flickr API, which is an example of a document and provides a very handy API test tool.

• Mediawiki API
• Ebay API, here is an example of a very detailed document.

Reference Address: http://www.biaodianfu.com/how-to-design-a-good-api.html

How to design a good API (GO)