Turn: how to design an excellent API

It has been more than two years since the API was provided for the client to call. Over the past two years, it has been a tear. After the API is launched, the Client Version keeps upgrading, the more features you have, the more complex APIs you have. At this time, your TMD must be compatible with the old system. After half a year, you can see that there are more than N people using the old system, I want to die. New

It has been more than two years since the API was provided for the client to call. Over the past two years, it has been a tear. After the API is launched, the Client Version keeps upgrading, the more features you have, the more complex APIs you have. At this time, your TMD must be compatible with the old system. After half a year, you can see that there are more than N people using the old system, I want to die. New

It has been more than two years since the API was provided for the client to call. Over the past two years, it has been a tear. After the API is launched, the Client Version keeps upgrading, the more features you have, the more complex APIs you have. At this time, your TMD must be compatible with the old system. After half a year, you can see that there are more than N people using the old system, I want to die. Open new interface? The old interface is ignored? This is not a solution...

So when I read this article, I will take a look at it. By the way, I will also learn it myself. what others say is not necessarily true. If you listen to it, you will understand it. (The APIS provided by the author are not the same as those provided by me, but they are not much different. They were originally .... It's been around for more than two years, right ?)

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

So far, I have been responsible for APIS for nearly two years. In the past two years, I have found that there are more and more problems with existing APIs, but many APIs can no longer be modified once released, real-time upgrade and maintenance are required. Once the API changes, it may bring a huge price to the relevant callers. the user needs to check all called code and adjust all relevant parts, these jobs are extra work for them. If you find related bugs after you have worked hard on these issues, the user will be even more affected. If the API changes frequently, the user will lose confidence in the provider and affect the current business.

But why do we need to modify the API? To make the API look more beautiful? To provide more functions? To provide better performance? Or do you just think it's time to change? For users, they prefer to use a stable but less fashionable API, which does not mean that we no longer improve the API. When the maintenance cost of a bad API is getting bigger and bigger, I Think We Should refactor it.

If I can try again later, what should I do with the excellent API?

Determining whether an API is excellent is not simply based on the first version, but depends on whether the API can still exist over time and whether it remains good. There are various types of interface, but a good API must meet the following requirements:

• Easy to learn: There are complete documents and provides as many examples as possible and code that can be copied-paste. Like other design jobs, you should apply the least surprising principle.
• Easy to use: it is easy to learn without complex programs and details. Flexible APIs allow sorting by field, custom paging, sorting, and filtering. A complete API means that all desired functions are included.
• Difficult to misuse: For detailed error prompts, some experienced users can directly use the API without reading the document.

For developers, the requirements are different:

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

The following is a summary of how to achieve the above:

1,Case-oriented design

If an API is widely used, it is impossible to understand all users who use the API. If the designer wants to design a widely used API, he must understand how to design the API library and how to design such an API library from the user's perspective.

2,Adopt good design ideas

In the design process, if you can design the API in the following ways, it will make the API a longer life.

• Use Case-oriented design, collection of user suggestions, simulation of yourself as a user, to ensure that the API design is easy to use and reasonable
• Ensure that subsequent requirements can be completed through extension
• The first version provides as few content as possible. Because new requirements can be completed in the form of extensions, doing as few things as possible is an effective solution to suppress API design errors.
• Provide clear API and documentation specifications to prevent users from using APIs incorrectly. In particular, avoid API (see section 1) Being known and misused by users at a lower level.

In addition, some specific design methods are listed below:

• Method is better than attribute
• The factory method is better than the constructor
• Avoid excessive inheritance
• Avoid affecting the API due to optimization or code reuse
• Interface-Oriented Programming
• Extension parameters should be convenient
• Properly locate components and determine how many interfaces are exposed
• Provide extension points

3,Avoid extreme comments

When designing APIs, you must avoid any extreme comments, especially the following:

• Must be nice (APIs may not be nice)
• The API must be correctly used (it is difficult for users to understand how to use the API correctly. The API designer should fully consider the misuse of the API: if an API may be misused, so it will be misused)
• It must be simple (we will always face complicated requirements, and the APIs that can take both of them into account are better APIs)
• High performance is required (performance can be optimized by other means, and the API design should not be affected)
• It must be absolutely compatible (although this article has always mentioned how to ensure compatibility, we still need to realize that incompatibility is tolerable in rare cases)

4,Effective API Review

After the API design is complete, it requires careful design review. The review focuses on the following:

• Case-driven, comprehensive use cases must be provided before review to ensure the rationality and completeness of the case.
• Consistency, whether it is consistent with the interface style of other modules in the system, and whether it is consistent with the design of symmetric interfaces.
• Simple and clear, the API should be easy to understand, and easy to learn and use is not easy to misuse, which brings us more trouble.
• As few APIs as possible. If an API can be exposed or not exposed, do not expose it. It is not too late to turn it into a public interface when the user really needs it.
• Continuous improvement is supported. Can APIs be easily added and optimized through expansion.

5,Improve API Testability

The API needs to be testable, and the test should not rely on implementation. The test should be adequate, especially the API that has passed the strict "compatibility integration test, it ensures that there are no compatibility issues during the upgrade process. Compatibility integration testing refers to a set of test cases. This set of testing routine uses APIs from the user's standpoint. After the API is upgraded, check whether this set of test cases can pass the test in full compliance with expectations to discover compatibility issues as much as possible.

6,Ensures API backward compatibility

Every API designer is eager to be "backward compatible", because both current API users and potential API users only trust compatible APIs. However, backward compatibility has the meaning of multiple levels. In addition, backward compatibility at different levels also means different importance and complexity.

7,Keep improving

In the past, we always hoped to completely overturn the existing "unreasonable" design and re-design this API based on the current "beautiful" concept. However, after a while, we will encounter the same situation and need to overturn it again. If we do not have an effective step-by-step improvement method, by overturning the existing design, re-designing the API can only let us go back to the starting point and reproduce the previous process. There should be a set of effective and continuous improvement methods to improve the API to make it better while the API is compatible.

8,Measure the test taker's knowledge about the API lifecycle.

Every API has a lifecycle. We need to extend the lifecycle of an API and make it die out smoothly when the lifecycle of an API ends.

• It tells users how to design, avoid misuse, and provide guidance. Incorrect use is often a major killer of shortening the API life.
• The trial period is provided, and the API cannot be stable at the beginning, so that the tested API can have a stronger vitality.
• API classification: internal use; secondary development and use; development or trial use; stable; abandon API. To avoid API abuse, we can adjust the API level to expand its influence, and end an API lifecycle more elegantly.

The process of developing APIS is actually a process of communication. Both parties are API users and API designers.

9,Some specific implementation solutions

When an API inevitably disappears or changes, we should accept and face this fact. The following lists several ways to adjust the API under the premise of ensuring compatibility:

• Mark the API as obsolete and create a new API. This is the only way to prevent an API from dying out.
• Add additional parameters or Parameter options for the feature
• Split existing APIs into two parts to provide a streamlined core API, which is achieved by encapsulating the core API. This is usually used to solve the need for a simplified version of code.
• Encapsulate existing APIs to provide a more functional package or Class

Some good API examples:

1. Here is an example of the document and provides a very convenient API testing tool.
2. Mediawiki API
3. Ebay API. Here is a very detailed document example.

---- EOF ---

In short, it is better to believe in books than to have no books. It is always correct to learn from them.

Original article address: Go: how to design an excellent API, thanks to the original author for sharing.