Do you feel the same way?
- When docking with the XX business, the functions and APIs of the XX business are all repeatedly inquired and confirmed by the person in charge of the running business. Which API to use; How to use it; There are no restrictions; Wait a minute
- API styles are not uniform across businesses, or even within the same business.
- API naming: fully translated by natural semantics; Defined by attribute perspective; defined by the angle of operation; moving, non-moving; plural, non-plural; etc. API input parameters: with Map; The same semantic field names are not the same; API parameters: Packaged Resoponse; Directly return the result data; For the same data, the return format and field name are different; Error message: Returns directly to the Chinese prompt; Returns the encoded prompt message; Returns the exception type; Wait a minute
- XX Business API performance is unknown.
- As the business evolves, open APIs continue to increase, but there are many similarities
API coding specifications are imminent
Idiosyncrasies of a great API
Self-explanatory
- From the API itself, you can understand at a glance what the API does, supported usages, applicable scenarios, exception handling, etc
Easy to learn
- There is well-documented documentation, as well as code that provides as many examples and copy-pastes as possible.
Easy to use
- Powerful, yet simple to use. It does not increase the cost of the caller (for example, requiring the business side to use the API and requires additional configuration and dependencies), and does not expose complex details and lengthy usage processes to the caller. The caller does only minimal perception and minimal passing parameters.
Difficult to misuse
- A good API allows experienced developers to use the API directly without having to read the documentation.
- Sufficient static checking, dynamic validation, explicit exception descriptions, and valid error messages.
API design principles
1. The principle of sufficiency
It is not necessary to have an interface for any function, nor is it necessary to add an interface for any requirement.
Every new interface must be built for a good reason and consideration, that is, the existence of this interface is very meaningful and valuable. The meaningless interface not only increases the difficulty of maintenance, but more importantly, the controllability of the program is greatly reduced, and the interface will be very bloated.
2. The principle of single perspective
When designing an interface, the angle of analysis should be uniform. Otherwise, it will cause confusion in the interface structure. For example: don't design from the perspective of the character one moment, design from the perspective of the function the next.
Recommendation: Define APIs from the perspective of "property object + behavior"
3. Single function principle
Each API should focus on one thing and do it well. The product concept is simple and the relationship is clear. Ambiguous functions, many special logic APIs are certainly not elegant APIs, and will cause similar functions to duplicate APIs.
Note: If the API is difficult to name, then this may be a bad omen, good names can drive development, and only need to split and merge modules.
Large, full-featured APIs are certainly stretched thin in terms of flexibility and simplicity. Before defining the granularity of APIs, it is recommended to extract business objects by dividing business domains and boundaries, and then design APIs with a single function according to the business object use case.
For example, to query a member, you may need to obtain other necessary information of the member in addition to the member form, but do not query the member while also modifying permissions and other similar business functions, which should be divided into two interfaces to execute.
4. The principle of simplicity
The interface design is simple and clear. The functions performed by APIs can be very rich and powerful, but API declarations and usage must be as simple as possible, and the richness of functions cannot be realized through complex usage, which will lead to API functions that are not single and evolution is uncontrollable.
The final review will depend on how simple the API is to use.
- Can you write examples that make your code look simpler?
- Are you forcing callers to focus on/provide options/configurations they don't care about?
- Are there any worthless extra steps?
Write code that is easy to read and understand so that others will appreciate it and be able to give you suggestions for rationalization. On the contrary, if it is a complicated program, others will always avoid it.
5. Abstract principles
The objects and attributes described in the input and exit parameters of the API must be entities abstracted according to business characteristics. Mistakenly reflect the underlying data model concepts to the API. Abstract APIs and abstract object entities are more macroscopic, with better applicability, compatibility, and extensibility.
6. Compatible with extension principles
Open for extensions, closed for modifications. Ensure backward compatibility of APIs.
Extension parameters should be convenient to ensure that similar requirements can be implemented through compatible extensions on existing APIs.
7. The principle of least surprise
The code should surprise the reader as little as possible. Business APIs only need to be designed according to requirements, and there is no need to deliberately design complex and useless APIs to avoid self-defeating.
8. Low coupling principle
APIs should reduce dependencies on other business code. Low coupling is often the hallmark of a perfect structural system and good design.
Types of coupling:
- The code implements the business reverse call.
- Conditional logic relies on coupling. For example, when this API handles the super order type of Guoshui Network, you need to send an additional MQ for the upload of settlement and payment vouchers.
- Coupling API-agnostic business behavior. For example, if the Purchase Plan Link Log API is called, if it is a project purchase order, you need to call the advertised API to pull the link information and create a link log for the order.
9. Orthogonality
Orthogonality refers to changing one property without affecting other properties.
The functions between the APIs should be orthogonal, with no functional overlap. APIs should complement each other.
10. Ease of testing principle
For API callers, the API should be testable and easy to test. Testing APIs do not need to rely on additional environments, containers, configurations, public services, etc.
A testable API is also a prerequisite for effective integration testing.
11. Principle of uniformity
APIs should have unified naming, uniform input/exit parameter specifications, unified exception specifications, unified error code specifications, and unified version specifications.
Advantages of a unified and standardized API:
- Easy to integrate and handle by the framework
- It is helpful for API callers and API providers to reuse development experience
- Avoid mistakes and avoid misuse