Shulou(Shulou.com)06/02 Report--

What is the design principle of API? I believe many inexperienced people are at a loss about it. Therefore, this paper summarizes the causes and solutions of the problem. Through this article, I hope you can solve this problem.

Do you feel the same way?

When docking the XX service, the function of the XX service and the API all depend on the person in charge of the running business to ask and confirm one by one. How to use which API;; is there any limit; etc.

The style of API is not uniform among different services, even within the same business.

API naming: fully translated by natural semantics; defined by attribute point of view; defined by operational point of view; verb-object, non-verb-object; plural, non-plural; etc.

API input parameter: with Map; the same semantic field name is different

API output parameters: those with packaged Resoponse; those that return result data directly; those with the same data, which are different in format and field name

Error message: directly return Chinese prompt; return prompt message encoded; return exception type; and so on

The performance of XX business API is unknown.

With the evolution of business, open API continues to increase, but there are many similarities.

API coding specification is imminent

The characteristics of excellent API

Self-explanation

You can see what API is, supported usage, applicable scenarios, exception handling, etc., at a glance from API itself.

Easy to learn

There is good documentation, as well as as many examples and copy-paste code as possible.

Easy to use

Powerful, but easy to use. It does not increase the cost of the caller (for example, additional configuration and dependencies are required when the business side is required to use API), and does not expose complex details and lengthy usage processes for callers to perceive. The caller does only the least perception and the least number of parameters.

Difficult to misuse

Good API allows experienced developers to use API directly without reading the documentation.

Full static check, dynamic check, explicit exception description, effective error prompt.

ZCY API Design principles 1. Sufficient principle

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 should be fully justified and considered, 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.

two。 Principle of single perspective

When designing the interface, the angle of analysis should be unified. Otherwise, it will cause confusion in the interface structure. For example: do not design from a character's point of view, but from a functional point of view.

Recommended: define API from the perspective of "attribute object + behavior"

3. Single function principle

Each API interface should focus on only one thing and do it well. The concept of the product is simple and the relationship is clear. Functional ambiguity, a lot of special logic of the API is certainly not an elegant API, and will result in functions similar to repetitive API.

Note: if API is difficult to name, it may be a bad sign that a good name can drive development and simply split and merge modules.

The full-featured API must be stretched in terms of flexibility and simplicity. Before defining the granularity of API, it is recommended to extract business objects by dividing the business into domains and boundaries, and then design a single-function API according to the business object use case.

For example: to inquire about a member, you may need to obtain other necessary information about the member in addition to querying the member list, but you should not query the member and also have other business functions such as modification authority, which should be divided into two interfaces.

4. Principle of simplicity

The interface design is simple and clear. The functions implemented by API can be very rich and powerful, but the declaration and usage of API must be as simple as possible, and the enrichment of functions can not be realized through complex usages, which will lead to the uncontrollable evolution of API.

The final review depends on the ease of use of the API.

Can the examples you write make your code look simpler?

Are you forcing callers to follow / provide options / configurations they don't care about?

Are there any worthless extra steps?

The code must be easy to read and understand so that others will appreciate it and give you reasonable suggestions. On the contrary, if it is a complicated program, others will always avoid it.

5. Abstract principle

The objects and attributes described in the input and output parameters of API must be abstract entities according to business characteristics. Mistakenly reflect the concept of the underlying data model to API. Abstract API and abstract object entities are more macroscopic and have better applicability, compatibility and expansibility.

6. Compatible extension principle

Open for extensions and closed for modifications. Ensure backward compatibility of API.

Extension parameters should be convenient to ensure that subsequent similar requirements can be implemented in a compatible extension on existing API.

7. The principle of least surprise

The code should be as little as possible to surprise the reader. Business API only needs to be designed according to the requirements, and there is no need to deliberately design a complex and useless, flashy API to avoid self-defeating.

8. Low coupling principle

API should reduce its dependency on other business code. Low coupling is often the symbol of perfect structural system and excellent design.

Types of coupling:

The code implements the reverse call of the business.

Conditional logic depends on coupling. For example, this API needs to send an additional event MQ uploaded to the settlement and payment voucher when dealing with the excess order type of the national tax network.

Coupling API-independent business behavior. For example, when the purchase plan link log API is called, in the case of a project purchase order, you need to call the announced API to pull the link information and create a new link log for this order.

9. Principle of orthogonality

Orthogonality refers to changing one feature without affecting others.

The functions of API should be orthogonal and non-functional overlap. API should be complementary to each other.

10. Principle of easy testing

For API callers, API should be testable and easy to test. Testing API does not need to rely on additional environments, containers, configurations, public services, and so on.

Testable-friendly API is also a prerequisite for effective integration testing.

11. Principle of unification

API should have unified naming, unified input / output parameter specification, unified exception specification, unified error code specification, unified version specification and so on.

API advantages of a unified specification:

Easy to be integrated and handled by the framework

It helps API callers and API providers to reuse their development experience.

Avoid making mistakes and avoiding misuse

After reading the above, have you mastered what the design principles of API are? If you want to learn more skills or want to know more about it, you are welcome to follow the industry information channel, thank you for reading!

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.