Do you feel the same way?
- When connecting to XX business, the functions and APIs of XX business depend on the person in charge of the business to repeatedly ask and confirm one by one. Which API to use; how to use it; are there any restrictions; etc.
- The API styles are not uniform between businesses, or even within the same business.
- API naming: fully translated according to natural semantics; defined from the perspective of attributes; defined from the perspective of operation; verb-object, non-verb-object; plural, non-plural; etc.
- API input parameters: with Map; the same semantic field names are different;
- API output parameters: those with packaging Resoponse; those that return the result data directly; those that return the same data, but have different return formats and field names;
- Error information: return Chinese prompt directly; return prompt information code; return exception type; etc.
- XX business API performance is unknown.
- With the evolution of business, open APIs continue to increase, but there are many similar
API coding standards are imminent
Traits of a good API
- self explanatory
- From the API itself, you can understand at a glance what the API does, supported usage, applicable scenarios, exception handling, etc.
- easy to learn
- There is good documentation, as well as providing as many examples and copy-pasteable code as possible.
- easy to use
- Powerful, yet simple to use. It does not increase the usage cost of the caller (such as requiring additional configuration and dependencies when the business side uses the API), and does not expose complex details and lengthy usage processes to the caller's perception. The caller does only minimal perception and minimal parameter passing.
- difficult to misuse
- A good API allows experienced developers to use the API directly without reading the documentation.
- Sufficient static checking, dynamic validation, explicit exception description, valid error message.
ZCY API Design Principles
1. The principle of sufficiency
It is not necessary to have an interface for any function, and it is not necessary to add an interface to any requirement.
Every time a new interface is created, there must be sufficient reasons and considerations, that is, the existence of this interface is very meaningful and valuable. The meaningless interface not only increases the difficulty of maintenance, but also greatly reduces the controllability of the program, and the interface will be very bloated.
2. The Single Perspective Principle
When designing the interface, the analysis angle should be unified. Otherwise, it will cause confusion in the interface structure. For example: Don't design from a character perspective for a while, but design from a functional perspective for a while.
Recommendation: Define APIs from a "property object + behavior" perspective
3. Single function principle
Each API interface should focus on only one thing and do it well. The product concept is simple and the relationship is clear. The functions are ambiguous, and many APIs with special logic are definitely not elegant APIs, and will result in similar and duplicated APIs.
Note: If the API is difficult to name, then this may be a bad sign, good names can drive development and simply split and merge modules.
A large and full-featured API must be stretched in terms of flexibility and simplicity. Before defining the granularity of the API, it is recommended to divide the business into fields and boundaries to extract business objects, and then design a single-function API according to the use cases of the business objects.
For example, when querying a member, it may be necessary to obtain other necessary information of the member in addition to querying the membership table, but it should be divided into two interfaces for execution.
4. The principle of simplicity
The interface design is simple and clear. The functions executed by the API can be very rich and powerful, but the API declaration and usage must be as simple as possible, and the richness of functions cannot be realized through complex usage, which will result in the API function is not single, and the evolution is uncontrollable.
The final review depends on the ease of use of the API.
- Can the example you wrote make your code look simpler?
- Are you forcing callers to care/provide options/configurations they don't care about?
- Are there worthless extra steps?
Write code that is easy to read and understand so others will appreciate it and give you rationalized advice. On the contrary, if it is complicated and difficult to understand, other people will always avoid it.
5. The principle of abstraction
The objects and attributes described in the input and output parameters of the API must be abstracted entities according to business characteristics. Mistakenly reflect the underlying data model concept to the API. Abstract API and abstract object entities are more macroscopic and have better applicability, compatibility and scalability.
6. Compatible extension principle
Open for extension, closed for modification. Guaranteed API backward compatibility.
Extension parameters should be convenient to ensure that subsequent similar requirements can be implemented in a compatible extension method on the existing API.
7. The principle of least astonishment
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, useless and flashy APIs to avoid self-defeating.
8. The principle of low coupling
APIs should reduce dependencies on other business code. Low coupling is often a sign of perfect structural systems and good design.
Kind of coupling:
- The code implements business reverse invocation.
- Conditional logic depends on coupling. For example, this API needs to send an additional event MQ for uploading settlement payment vouchers when processing the over-order type of the national tax network.
- Coupling API-independent business behaviors. For example, when the procurement plan link log API is called, in the case of a project purchase order, it is necessary to additionally call the announced API to pull the link information, and create a new link log for this order.
9. Orthogonality
Orthogonality refers to changing one property without affecting other properties.
The functions between APIs should be orthogonal, and there should be no functional overlap. APIs should be complementary to each other.
10. Ease of testing
APIs should be testable and easy to test for API callers. Testing APIs does not require dependencies on additional environments, containers, configurations, public services, etc.
A testable-friendly API is also a prerequisite for effective integration testing.
11. The principle of unity
The API must have a unified naming, a unified input/output parameter specification, a unified exception specification, a unified error code specification, and a unified version specification.
Unified specification API advantages:
- Easy to be integrated and handled by the framework
- Helps API callers and API providers to reuse development experience
- avoid mistakes, avoid misuse